@usine/github 0.1.2 → 0.3.0

package/README.md

@@ -1,41 +1,23 @@
 # @usine/github
 
-`@usine/github` gives an usine factory one GitHub App identity. It signs App JWTs, finds the App's installation, reports registry repositories that the installation does not cover, and mints two kinds of installation token:
+Gives a usine factory one GitHub App identity. It signs App JWTs, finds the App's installation, reports registry repos that the installation doesn't cover, and mints two kinds of installation token:
 
 - an installation-wide token for orchestrator polling and writes;
-- a token restricted to one repository for a worker attempt.
+- a token for one repo, for a worker attempt.
 
-Both token requests use a one-hour maximum lifetime. Expiry validation tolerates up to three minutes of clock skew while capping the local lease at one hour; expired tokens are rejected. Token values and the App private key stay inside Effect `Redacted` values.
+Both tokens have a one-hour maximum lifetime. Expiry validation tolerates three minutes of clock skew and caps the local lease at one hour; expired tokens are rejected. Token values and the private key stay in Effect `Redacted` values.
 
-Import `GitHubApp`, credentials, access results, and typed App errors from `@usine/github/github-app`. `@usine/github/polling` provides `GitHubPolling` with its cursors, change-detection results, and payload snapshots. Item and label writes use `/item-writer` and `/label-writer`; local credential loading uses `/local-secrets`.
+Import `GitHubApp`, credentials, access results, and typed App errors from `@usine/github/github-app`. `/polling` provides `GitHubPolling` with its cursors, change-detection results, and payload snapshots, plus `RepositoryLabel`, `RepositoryLabelCatalog`, and `RepositoryLabelsNotModified` for label catalogs and conditional responses. Item and label writes use `/item-writer` and `/label-writer`, the App's own changes on an item come from `/item-history`, and local credential loading uses `/local-secrets`.
 
-`/polling` also exports `RepositoryLabel`, `RepositoryLabelCatalog`, and
-`RepositoryLabelsNotModified` for reading label catalogs and handling conditional
-responses. These contracts share the same entry point as `GitHubPolling`.
+The 0.x APIs can change between minor releases.
 
-## Create the App manually
+## Set up the App
 
-Open your GitHub account or organization settings, select **Developer settings → GitHub Apps**, then select **New GitHub App**. Use a name that identifies the factory and set **Where can this GitHub App be installed?** to **Only on this account**. User authorization isn't required. You can turn off active webhooks for a polling-only development factory.
+[Run a factory](https://docs.usine.dev/guides/) gives the steps under Connect a GitHub App: an App installable only on your account, without active webhooks, with Contents, Issues, and Pull requests read and write, Checks and Metadata read-only, and **No access** for everything else, including Workflows, Administration, and all organization and account permissions.
 
-Set these repository permissions:
+GitHub grants Metadata read access automatically. Contents lets installation tokens use Git over HTTPS; with Workflows off, worker tokens can't edit `.github/workflows/`. User authorization isn't required. Install the App once, on the account that owns the managed repos, for every repo in `usine.yaml`; a factory expects one installation. GitHub's references are [Registering a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app) and [Choosing permissions for a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app).
 
-| Permission | Access |
-| --- | --- |
-| Metadata | Read-only |
-| Contents | Read and write |
-| Issues | Read and write |
-| Pull requests | Read and write |
-| Checks | Read-only |
-
-Leave Workflows, Administration, every organization permission, and every account permission at **No access**. GitHub grants Metadata read access automatically. The Contents permission lets installation tokens authenticate Git over HTTPS; Workflows remains off, so worker tokens cannot edit files under `.github/workflows/`.
-
-Create the App, generate a private key, and note the numeric App ID. On the App's **Install App** page, install it on the account that owns the factory's managed repositories. Select every repository listed in `usine.yaml`. A factory expects one App installation, so don't install the same App on a second account.
-
-GitHub's current setup references are [Registering a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app) and [Choosing permissions for a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app).
-
-## Store the credentials
-
-The local runtime file is `<instance>/.usine/github-app.json`. Keep `.usine/` in the instance repo's `.gitignore`, and set the file mode to `0600`.
+Store the App ID and private key in `<instance>/.usine/github-app.json` with mode `0600`, and keep `.usine/` in the instance repo's `.gitignore`:
 
 ```json
 {
@@ -44,20 +26,11 @@ The local runtime file is `<instance>/.usine/github-app.json`. Keep `.usine/` in
 }
 ```
 
-This command creates the JSON without copying PEM newlines by hand:
-
-```sh
-mkdir -p .usine
-install -m 600 /dev/null .usine/github-app.json
-jq -n --argjson app_id "$APP_ID" --rawfile private_key factory.private-key.pem \
-  '{app_id: $app_id, private_key: $private_key}' > .usine/github-app.json
-```
-
-`USINE_GITHUB_APP_ID` and `USINE_GITHUB_PRIVATE_KEY` override their matching file fields. When both variables exist, the loader does not read the file.
+`USINE_GITHUB_APP_ID` and `USINE_GITHUB_PRIVATE_KEY` override the matching fields. If both are set, the loader doesn't read the file.
 
 ## Compose the services
 
-The package root has no Node dependency. Supply an HTTP client plus platform file and path layers at the application edge:
+The package root has no Node dependency. Supply an HTTP client and platform file and path layers at the edge:
 
 ```ts
 import { NodeFileSystem, NodePath } from "@effect/platform-node"
@@ -65,7 +38,7 @@ import { InstanceDirectory } from "@usine/core/instance"
 import { GitHubApp } from "@usine/github/github-app"
 import { localSecretsLayer } from "@usine/github/local-secrets"
 import { Layer } from "effect"
-import { FetchHttpClient } from "effect/unstable/http"
+import { FetchHttpClient } from "effect/http"
 
 const instance = InstanceDirectory.make("/path/to/instance")
 const platformLayer = Layer.merge(NodeFileSystem.layer, NodePath.layer)
@@ -79,33 +52,41 @@ export const githubLayer = GitHubApp.layer.pipe(
 )
 ```
 
-`GitHubApp.layer` imports the private key once, when the layer is built: a key WebCrypto cannot import fails composition with `AppAuthenticationError` instead of failing the first request. Another credential source provides `GitHubCredentials` with an `AppCredentials` whose key went through the `RedactedPrivateKey` schema.
+`GitHubApp.layer` imports the private key once, at build time, so a key that WebCrypto can't import fails composition with `AppAuthenticationError`, not the first request. Another credential source provides `GitHubCredentials` with `AppCredentials` whose key went through the `RedactedPrivateKey` schema.
+
+`installation()`, `installationToken()`, and `projectAccess()` share one lease: one installation discovery and installation-wide mint, reused until five minutes before expiry, so polling makes no App requests between renewals. `workerToken()` mints on every call, so each attempt gets its own token.
 
-`installation()`, `installationToken()`, and `projectAccess()` share one lease: a single installation discovery and installation-wide mint, reused until five minutes before the token expires. Polling therefore costs no App requests between renewals. `workerToken()` mints on every call, so each attempt gets its own token.
+`botAccount()` returns the App's bot account, `<slug>[bot]` and its user ID, which differs from the App ID. It reads `GET /users/<slug>[bot]` with the installation-wide token once per slug. Commits use the account's ID-based noreply address, `<id>+<slug>[bot]@users.noreply.github.com`.
 
-Call `GitHubApp.projectAccess(registry)` before scheduling work. Each result is either a `CoveredProject`, which carries the repository ID needed for scoped minting, or a `ProjectNotInstalledError`. A missing repository does not block covered projects.
+Call `GitHubApp.projectAccess(registry)` before scheduling. Each result is a `CoveredProject`, with the repo ID for scoped minting, or a `ProjectNotInstalledError`. A missing repo doesn't block covered ones.
 
-Pass a `CoveredProject` to `GitHubApp.workerToken`. GitHub must confirm in the token response that the token covers exactly that repository ID; otherwise the call fails with `InvalidGitHubResponseError`.
+Pass a `CoveredProject` and the attempt's loop permission level to `GitHubApp.workerToken`. If GitHub's response doesn't confirm that the token covers exactly that repo ID, it fails with `InvalidGitHubResponseError`. `WORKER_TOKEN_PERMISSIONS` lists each level's permissions: a `read` token has `contents: read`, so it can't push, and keeps `pull_requests: write` and `issues: write` for reviews and comments.
 
 ## Poll repository changes
 
-`GitHubPollingLayer` supplies the operations the orchestrator needs:
+`GitHubPollingLayer` provides:
 
-- `changes(repository, cursor)` makes one conditional Issues REST request. It returns changed issue and pull-request numbers, the next ETag and watermark, plus any rate-limit delay GitHub requested.
-- `labels(repository)` reads every page of the repository label catalog for Board lane proposals.
+- `changes(repository, cursor)`: one conditional Issues REST request, returning changed issue and pull request numbers, the next ETag and watermark, and any rate-limit delay.
+- `labels(repository)`: every page of the repo's label catalog, for board lane proposals.
+- `baseRefHead(repository, baseRefName, known)`: the head commit of a base branch, from one conditional Git refs REST request with the ETag of `known`. A 304 returns `known` and costs no rate limit; a missing branch fails with a 404 `GitHubApiError`.
+- `snapshot(repository, item)`: the issue or pull request payload through GraphQL, with its SHA-256 content hash. The stored payload keeps timestamps; the hash excludes timestamp fields at every level.
+- `missingIssues(repository, numbers)`: the numbers the repo no longer has, deleted or transferred. It sends one GraphQL request per 50 numbers, with an aliased `issue(number:)` field each; an issue that returns null is missing.
 
-Change-detection results distinguish `nextPollAt`, the earliest next conditional poll, from `backoffUntil`, a request delay caused by `Retry-After` or rate-limit pressure. Self-write Hints can fetch an Item snapshot during the normal poll interval while respecting request backoff.
-- `snapshot(repository, item)` fetches the issue or pull-request payload through GraphQL and computes its SHA-256 content hash. The stored payload retains timestamps, while the hash excludes timestamp fields at every nesting level.
+Change detection separates `nextPollAt`, the earliest next conditional poll, from `backoffUntil`, a delay from `Retry-After` or rate-limit pressure. Self-write hints can fetch a snapshot within the poll interval while respecting backoff.
 
-The REST cursor overlaps its watermark by five seconds. Repeated items are expected; the engine's permanent Event ledger owns deduplication. Provide `GitHubPollingLayer` with `GitHubApp`, an Effect HTTP client, and `Crypto.Crypto`. The package root remains platform-free.
+The REST cursor overlaps its watermark by five seconds. Repeated items are expected; the engine's event ledger deduplicates. Provide `GitHubPollingLayer` with `GitHubApp`, an Effect HTTP client, and `Crypto.Crypto`.
 
-`GitHubItemWriter.updateLabels(repository, item, mutation)` adds destination lane labels and removes only explicitly lane-owned labels from an issue or pull request. It never replaces the complete applied-label set or deletes repository label definitions, so unrelated and concurrently added labels survive stale or truncated Item projections. The service requires `GitHubApp` and an Effect HTTP client.
+`GitHubItemWriter.updateLabels(repository, item, mutation)` adds the destination lane's labels and removes only labels that lanes own. It never replaces an item's whole label set or deletes label definitions, so unrelated and concurrent labels survive stale or truncated projections.
 
-`GitHubLabelWriter.create(repository, label)` creates one repository label through `POST /repos/{owner}/{repo}/labels` using the installation-wide App token. Provide a name; color and description are optional. Reconciliation policy belongs to the orchestrator, so this service exposes creation only and never edits or deletes label definitions.
+`GitHubItemHistory.appChanges(repository, item, since)` (`/item-history`) reads an issue or pull request timeline through GraphQL from `since`, and returns the factory App's own changes, oldest first: `LabelAdded`, `LabelRemoved`, `Commented`, and `Reviewed` (a submitted review with its state). Each change has GitHub's time; a label has its current name, color, and description, and comments and reviews have their URL. Other users and bots are left out. The App is matched by its slug, `Installation.appSlug` from `GitHubApp.installation()`, since GraphQL reports its writes with a `Bot` actor of that login. It reads up to ten pages of 100 items and fails with `InvalidGitHubResponseError` rather than return part of a longer timeline. An item the repo no longer has fails with `GitHubItemNotFoundError`.
 
-## Real-App integration check
+`GitHubLabelWriter.create(repository, label)` creates a label through `POST /repos/{owner}/{repo}/labels` with the installation-wide token. Color and description are optional. The orchestrator owns reconciliation, so this service only creates.
 
-Run the opt-in integration test against a disposable issue in a repository covered by the App:
+The item writer, item history, and label writer each need `GitHubApp` and an Effect HTTP client.
+
+## Real-App integration test
+
+Run the opt-in test against a disposable issue in a repo the App covers:
 
 ```sh
 export USINE_GITHUB_INTEGRATION_INSTANCE_DIRECTORY=/path/to/instance
@@ -115,6 +96,4 @@ export 'USINE_GITHUB_INTEGRATION_BOT_LOGIN=your-app-slug[bot]'
 pnpm --filter @usine/github test:integration
 ```
 
-The test mints both token shapes, posts one issue comment with the repository-scoped token, checks the comment author against the expected `<app>[bot]` login, and deletes the comment during cleanup. `@usine/orchestrator` has a separate live polling test that temporarily creates and applies a repository label.
-
-All APIs remain 0.x and can change between minor releases.
+It mints both token kinds, posts an issue comment with the repo token, checks the author against `<app>[bot]`, and deletes the comment at cleanup. `@usine/orchestrator` has a separate live polling test that creates and applies a repo label.

package/dist/access.d.ts

@@ -1,7 +1,7 @@
 import { RepositoryName } from "@usine/core/repository";
 import { Schema } from "effect";
 import { RepositoryId, Installation } from "./installation.ts";
-/** Repository grants required for polling, label updates, and agent-authored changes. */
+/** The repository permissions required for polling, label updates, and agent-authored changes. */
 export declare const REQUIRED_REPOSITORY_PERMISSIONS: {
     readonly checks: "read";
     readonly contents: "write";
@@ -10,38 +10,60 @@ export declare const REQUIRED_REPOSITORY_PERMISSIONS: {
     readonly pull_requests: "write";
 };
 export type RequiredRepositoryPermission = keyof typeof REQUIRED_REPOSITORY_PERMISSIONS;
-/** The required repository permissions an installation grant does not satisfy, as `name:level` strings. */
+/**
+ * The repository permissions of an Attempt's token for each Loop permission level (ADR 0011).
+ * A `read` token can read code and post reviews and comments (`pull_requests` and `issues` are
+ * `write`), but can't push, merge, or update a branch, which need `contents: write`. Names and
+ * levels follow the installation token API:
+ * https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps
+ */
+export declare const WORKER_TOKEN_PERMISSIONS: {
+    readonly write: {
+        readonly checks: "read";
+        readonly contents: "write";
+        readonly issues: "write";
+        readonly metadata: "read";
+        readonly pull_requests: "write";
+    };
+    readonly read: {
+        readonly checks: "read";
+        readonly contents: "read";
+        readonly issues: "write";
+        readonly metadata: "read";
+        readonly pull_requests: "write";
+    };
+};
+/** Returns the required repository permissions that `granted` doesn't satisfy, as `name:level` strings. */
 export declare const missingPermissions: (granted: Readonly<Record<string, string>>) => ReadonlyArray<string>;
 declare const CoveredProject_base: Schema.Class<CoveredProject, Schema.TaggedStruct<"CoveredProject", {
     readonly installationId: Schema.brand<Schema.Int, "GitHubInstallationId">;
     readonly repository: Schema.brand<Schema.String, "RepositoryName">;
     readonly repositoryId: Schema.brand<Schema.Int, "GitHubRepositoryId">;
 }>, {}>;
-/** A registered repository covered by the discovered GitHub App installation. */
+/** A registered repository covered by the GitHub App installation. */
 export declare class CoveredProject extends CoveredProject_base {
 }
 declare const ProjectNotInstalledError_base: Schema.Class<ProjectNotInstalledError, Schema.TaggedStruct<"ProjectNotInstalledError", {
     readonly repository: Schema.brand<Schema.String, "RepositoryName">;
     readonly message: Schema.NonEmptyString;
 }>, import("effect/Cause").YieldableError>;
-/** A registry repository the installation does not cover. Raised per project, so covered siblings still load. */
+/** The error for a registry repository the installation doesn't cover. Reported per project, so covered projects still load. */
 export declare class ProjectNotInstalledError extends ProjectNotInstalledError_base {
 }
-/** The installation coverage result for one registered repository. */
+/** The installation coverage of one registered repository. */
 export declare const ProjectAccess: Schema.Union<readonly [typeof CoveredProject, typeof ProjectNotInstalledError]>;
 export type ProjectAccess = typeof ProjectAccess.Type;
-/** A repository reported by GitHub for an installation, identified by its numeric id and full name. */
 export interface InstalledRepository {
     readonly id: RepositoryId;
     readonly name: RepositoryName;
 }
-/** Checks each registry repository against the installation's repositories and returns one `ProjectAccess` per project. */
+/** Returns one `ProjectAccess` per registry repository by checking it against the installation's repositories. */
 export declare const deriveProjectAccess: (installation: Installation, registry: ReadonlyArray<RepositoryName>, installed: ReadonlyArray<InstalledRepository>) => ReadonlyArray<ProjectAccess>;
 declare const AppPermissionError_base: Schema.Class<AppPermissionError, Schema.TaggedStruct<"AppPermissionError", {
     readonly missing: Schema.$Array<Schema.NonEmptyString>;
     readonly message: Schema.NonEmptyString;
 }>, import("effect/Cause").YieldableError>;
-/** The installation lacks required repository grants; missing entries use name:level form. */
+/** The error when the installation lacks required repository permissions; `missing` uses `name:level` form. */
 export declare class AppPermissionError extends AppPermissionError_base {
 }
 export {};

package/dist/access.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAkB,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE/E,yFAAyF;AACzF,eAAO,MAAM,+BAA+B;aAC1C,MAAM,EAAE,MAAM;aACd,QAAQ,EAAE,OAAO;aACjB,MAAM,EAAE,OAAO;aACf,QAAQ,EAAE,MAAM;aAChB,aAAa,EAAE,OAAO;CACd,CAAC;AAEX,MAAM,MAAM,4BAA4B,GAAG,MAAM,OAAO,+BAA+B,CAAC;AAKxF,2GAA2G;AAC3G,eAAO,MAAM,kBAAkB,YACpB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KACxC,aAAa,CAAC,MAAM,CAGpB,CAAC;;;;;;AAEJ,iFAAiF;AACjF,qBAAa,cAAe,SAAQ,mBAMlC;CAAG;;;;;AAEL,iHAAiH;AACjH,qBAAa,wBAAyB,SAAQ,6BAK5C;CAAG;AAEL,sEAAsE;AACtE,eAAO,MAAM,aAAa,iFAA2D,CAAC;AACtF,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAC;AAEtD,uGAAuG;AACvG,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;CAC/B;AAED,2HAA2H;AAC3H,eAAO,MAAM,mBAAmB,iBAChB,YAAY,YAChB,aAAa,CAAC,cAAc,CAAC,aAC5B,aAAa,CAAC,mBAAmB,CAAC,KAC5C,aAAa,CAAC,aAAa,CAe7B,CAAC;;;;;AAEF,8FAA8F;AAC9F,qBAAa,kBAAmB,SAAQ,uBAKtC;CAAG"}
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAkB,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE/E,kGAAkG;AAClG,eAAO,MAAM,+BAA+B;aAC1C,MAAM,EAAE,MAAM;aACd,QAAQ,EAAE,OAAO;aACjB,MAAM,EAAE,OAAO;aACf,QAAQ,EAAE,MAAM;aAChB,aAAa,EAAE,OAAO;CACd,CAAC;AAEX,MAAM,MAAM,4BAA4B,GAAG,MAAM,OAAO,+BAA+B,CAAC;AAExF;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB;;iBAEjC,MAAM,EAAE,MAAM;iBACd,QAAQ,EAAE,OAAO;iBACjB,MAAM,EAAE,OAAO;iBACf,QAAQ,EAAE,MAAM;iBAChB,aAAa,EAAE,OAAO;;;iBAGtB,MAAM,EAAE,MAAM;iBACd,QAAQ,EAAE,MAAM;iBAChB,MAAM,EAAE,OAAO;iBACf,QAAQ,EAAE,MAAM;iBAChB,aAAa,EAAE,OAAO;;CAKzB,CAAC;AAKF,2GAA2G;AAC3G,eAAO,MAAM,kBAAkB,YACpB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KACxC,aAAa,CAAC,MAAM,CAGpB,CAAC;;;;;;AAEJ,sEAAsE;AACtE,qBAAa,cAAe,SAAQ,mBAMlC;CAAG;;;;;AAEL,gIAAgI;AAChI,qBAAa,wBAAyB,SAAQ,6BAK5C;CAAG;AAEL,8DAA8D;AAC9D,eAAO,MAAM,aAAa,iFAA2D,CAAC;AACtF,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAC;AAEtD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;CAC/B;AAED,kHAAkH;AAClH,eAAO,MAAM,mBAAmB,iBAChB,YAAY,YAChB,aAAa,CAAC,cAAc,CAAC,aAC5B,aAAa,CAAC,mBAAmB,CAAC,KAC5C,aAAa,CAAC,aAAa,CAe7B,CAAC;;;;;AAEF,+GAA+G;AAC/G,qBAAa,kBAAmB,SAAQ,uBAKtC;CAAG"}

package/dist/access.js

@@ -1,7 +1,7 @@
 import { RepositoryName } from "@usine/core/repository";
 import { Schema } from "effect";
 import { InstallationId, RepositoryId, Installation } from "./installation.js";
-/** Repository grants required for polling, label updates, and agent-authored changes. */
+/** The repository permissions required for polling, label updates, and agent-authored changes. */
 export const REQUIRED_REPOSITORY_PERMISSIONS = {
     checks: "read",
     contents: "write",
@@ -9,25 +9,48 @@ export const REQUIRED_REPOSITORY_PERMISSIONS = {
     metadata: "read",
     pull_requests: "write",
 };
+/**
+ * The repository permissions of an Attempt's token for each Loop permission level (ADR 0011).
+ * A `read` token can read code and post reviews and comments (`pull_requests` and `issues` are
+ * `write`), but can't push, merge, or update a branch, which need `contents: write`. Names and
+ * levels follow the installation token API:
+ * https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps
+ */
+export const WORKER_TOKEN_PERMISSIONS = {
+    write: {
+        checks: "read",
+        contents: "write",
+        issues: "write",
+        metadata: "read",
+        pull_requests: "write",
+    },
+    read: {
+        checks: "read",
+        contents: "read",
+        issues: "write",
+        metadata: "read",
+        pull_requests: "write",
+    },
+};
 const grants = (actual, required) => actual === required || (required === "read" && actual === "write");
-/** The required repository permissions an installation grant does not satisfy, as `name:level` strings. */
+/** Returns the required repository permissions that `granted` doesn't satisfy, as `name:level` strings. */
 export const missingPermissions = (granted) => Object.entries(REQUIRED_REPOSITORY_PERMISSIONS).flatMap(([permission, required]) => grants(granted[permission], required) ? [] : [`${permission}:${required}`]);
-/** A registered repository covered by the discovered GitHub App installation. */
+/** A registered repository covered by the GitHub App installation. */
 export class CoveredProject extends Schema.TaggedClass("@usine/github/ProjectAccess/CoveredProject")("CoveredProject", {
     installationId: InstallationId,
     repository: RepositoryName,
     repositoryId: RepositoryId,
 }) {
 }
-/** A registry repository the installation does not cover. Raised per project, so covered siblings still load. */
+/** The error for a registry repository the installation doesn't cover. Reported per project, so covered projects still load. */
 export class ProjectNotInstalledError extends Schema.TaggedError("@usine/github/ProjectNotInstalledError")("ProjectNotInstalledError", {
     repository: RepositoryName,
     message: Schema.NonEmptyString,
 }) {
 }
-/** The installation coverage result for one registered repository. */
+/** The installation coverage of one registered repository. */
 export const ProjectAccess = Schema.Union([CoveredProject, ProjectNotInstalledError]);
-/** Checks each registry repository against the installation's repositories and returns one `ProjectAccess` per project. */
+/** Returns one `ProjectAccess` per registry repository by checking it against the installation's repositories. */
 export const deriveProjectAccess = (installation, registry, installed) => {
     const byName = new Map(installed.map((repo) => [repo.name.toLowerCase(), repo]));
     return registry.map((repository) => {
@@ -35,7 +58,7 @@ export const deriveProjectAccess = (installation, registry, installed) => {
         return match === undefined
             ? new ProjectNotInstalledError({
                 repository,
-                message: `The GitHub App installation does not cover ${repository}`,
+                message: `The GitHub App installation has no access to "${repository}"`,
             })
             : new CoveredProject({
                 installationId: installation.id,
@@ -44,7 +67,7 @@ export const deriveProjectAccess = (installation, registry, installed) => {
             });
     });
 };
-/** The installation lacks required repository grants; missing entries use name:level form. */
+/** The error when the installation lacks required repository permissions; `missing` uses `name:level` form. */
 export class AppPermissionError extends Schema.TaggedError("@usine/github/AppPermissionError")("AppPermissionError", {
     missing: Schema.Array(Schema.NonEmptyString).check(Schema.isNonEmpty()),
     message: Schema.NonEmptyString,

package/dist/access.js.map

@@ -1 +1 @@
-{"version":3,"file":"access.js","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"access.js","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"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"}

package/dist/credentials.d.ts

@@ -1,27 +1,27 @@
 import { Context, Schema } from "effect";
-/** The numeric GitHub App identity included in signed App JWTs. */
+/** The numeric GitHub App ID included in signed App JWTs. */
 export declare const AppId: Schema.brand<Schema.Int, "GitHubAppId">;
 export type AppId = typeof AppId.Type;
-/** A PEM-encoded RSA private key used to authenticate the GitHub App. */
+/** A PEM-encoded RSA private key for the GitHub App. */
 export declare const PrivateKey: Schema.brand<Schema.NonEmptyString, "GitHubAppPrivateKey">;
 export type PrivateKey = typeof PrivateKey.Type;
-/** An App signing key that stays redacted in diagnostics and cannot be encoded. */
+/** The App private key, redacted in diagnostics and not encodable. */
 export declare const RedactedPrivateKey: Schema.RedactedFromValue<Schema.brand<Schema.NonEmptyString, "GitHubAppPrivateKey">>;
 declare const AppCredentials_base: Schema.Class<AppCredentials, Schema.Struct<{
     readonly appId: Schema.brand<Schema.Int, "GitHubAppId">;
     readonly privateKey: Schema.RedactedFromValue<Schema.brand<Schema.NonEmptyString, "GitHubAppPrivateKey">>;
 }>, {}>;
-/** The App credentials the orchestrator keeps and never passes to a worker. */
+/** The App credentials, kept by the orchestrator and never passed to a Worker. */
 export declare class AppCredentials extends AppCredentials_base {
 }
 declare const GitHubCredentials_base: Context.ServiceClass<GitHubCredentials, "@usine/github/GitHubCredentials", AppCredentials>;
-/** Supplies `AppCredentials`, so where credentials come from stays separate from how the App uses them. */
+/** The service that provides `AppCredentials`. */
 export declare class GitHubCredentials extends GitHubCredentials_base {
 }
 declare const AppAuthenticationError_base: Schema.Class<AppAuthenticationError, Schema.TaggedStruct<"AppAuthenticationError", {
     readonly message: Schema.NonEmptyString;
 }>, import("effect/Cause").YieldableError>;
-/** The App private key cannot sign. Raised once, when the App layer is built. */
+/** The error when the App private key can't sign, raised once when the App layer is built. */
 export declare class AppAuthenticationError extends AppAuthenticationError_base {
 }
 export {};

package/dist/credentials.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEzC,mEAAmE;AACnE,eAAO,MAAM,KAAK,yCAEjB,CAAC;AACF,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAC;AAEtC,yEAAyE;AACzE,eAAO,MAAM,UAAU,4DAKoB,CAAC;AAC5C,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,IAAI,CAAC;AAEhD,mFAAmF;AACnF,eAAO,MAAM,kBAAkB,sFAAiE,CAAC;;;;;AAEjG,+EAA+E;AAC/E,qBAAa,cAAe,SAAQ,mBAGlC;CAAG;;AAEL,2GAA2G;AAC3G,qBAAa,iBAAkB,SAAQ,sBAEtC;CAAG;;;;AAEJ,iFAAiF;AACjF,qBAAa,sBAAuB,SAAQ,2BAI1C;CAAG"}
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEzC,6DAA6D;AAC7D,eAAO,MAAM,KAAK,yCAEjB,CAAC;AACF,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAC;AAEtC,wDAAwD;AACxD,eAAO,MAAM,UAAU,4DAKoB,CAAC;AAC5C,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,IAAI,CAAC;AAEhD,sEAAsE;AACtE,eAAO,MAAM,kBAAkB,sFAAiE,CAAC;;;;;AAEjG,kFAAkF;AAClF,qBAAa,cAAe,SAAQ,mBAGlC;CAAG;;AAEL,kDAAkD;AAClD,qBAAa,iBAAkB,SAAQ,sBAEtC;CAAG;;;;AAEJ,8FAA8F;AAC9F,qBAAa,sBAAuB,SAAQ,2BAI1C;CAAG"}

package/dist/credentials.js

@@ -1,20 +1,20 @@
 import { Context, Schema } from "effect";
-/** The numeric GitHub App identity included in signed App JWTs. */
+/** The numeric GitHub App ID included in signed App JWTs. */
 export const AppId = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)).pipe(Schema.brand("GitHubAppId"));
-/** A PEM-encoded RSA private key used to authenticate the GitHub App. */
+/** A PEM-encoded RSA private key for the GitHub App. */
 export const PrivateKey = Schema.NonEmptyString.check(Schema.isPattern(/^-----BEGIN (?:RSA )?PRIVATE KEY-----[\s\S]+-----END (?:RSA )?PRIVATE KEY-----\s*$/u, { message: "Expected a PEM-encoded RSA private key" })).pipe(Schema.brand("GitHubAppPrivateKey"));
-/** An App signing key that stays redacted in diagnostics and cannot be encoded. */
+/** The App private key, redacted in diagnostics and not encodable. */
 export const RedactedPrivateKey = Schema.RedactedFromValue(PrivateKey, { disallowEncode: true });
-/** The App credentials the orchestrator keeps and never passes to a worker. */
+/** The App credentials, kept by the orchestrator and never passed to a Worker. */
 export class AppCredentials extends Schema.Class("@usine/github/AppCredentials")({
     appId: AppId,
     privateKey: RedactedPrivateKey,
 }) {
 }
-/** Supplies `AppCredentials`, so where credentials come from stays separate from how the App uses them. */
+/** The service that provides `AppCredentials`. */
 export class GitHubCredentials extends Context.Service()("@usine/github/GitHubCredentials") {
 }
-/** The App private key cannot sign. Raised once, when the App layer is built. */
+/** The error when the App private key can't sign, raised once when the App layer is built. */
 export class AppAuthenticationError extends Schema.TaggedError("@usine/github/AppAuthenticationError")("AppAuthenticationError", {
     message: Schema.NonEmptyString,
 }) {

package/dist/credentials.js.map

@@ -1 +1 @@
-{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEzC,mEAAmE;AACnE,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAC1E,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAC5B,CAAC;AAGF,yEAAyE;AACzE,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CACnD,MAAM,CAAC,SAAS,CACd,qFAAqF,EACrF,EAAE,OAAO,EAAE,wCAAwC,EAAE,CACtD,CACF,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC,CAAC;AAG5C,mFAAmF;AACnF,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC,iBAAiB,CAAC,UAAU,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC;AAEjG,+EAA+E;AAC/E,MAAM,OAAO,cAAe,SAAQ,MAAM,CAAC,KAAK,CAAiB,8BAA8B,CAAC,CAAC;IAC/F,KAAK,EAAE,KAAK;IACZ,UAAU,EAAE,kBAAkB;CAC/B,CAAC;CAAG;AAEL,2GAA2G;AAC3G,MAAM,OAAO,iBAAkB,SAAQ,OAAO,CAAC,OAAO,EAAqC,CACzF,iCAAiC,CAClC;CAAG;AAEJ,iFAAiF;AACjF,MAAM,OAAO,sBAAuB,SAAQ,MAAM,CAAC,WAAW,CAC5D,sCAAsC,CACvC,CAAC,wBAAwB,EAAE;IAC1B,OAAO,EAAE,MAAM,CAAC,cAAc;CAC/B,CAAC;CAAG"}
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEzC,6DAA6D;AAC7D,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAC1E,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAC5B,CAAC;AAGF,wDAAwD;AACxD,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CACnD,MAAM,CAAC,SAAS,CACd,qFAAqF,EACrF,EAAE,OAAO,EAAE,wCAAwC,EAAE,CACtD,CACF,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC,CAAC;AAG5C,sEAAsE;AACtE,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC,iBAAiB,CAAC,UAAU,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC;AAEjG,kFAAkF;AAClF,MAAM,OAAO,cAAe,SAAQ,MAAM,CAAC,KAAK,CAAiB,8BAA8B,CAAC,CAAC;IAC/F,KAAK,EAAE,KAAK;IACZ,UAAU,EAAE,kBAAkB;CAC/B,CAAC;CAAG;AAEL,kDAAkD;AAClD,MAAM,OAAO,iBAAkB,SAAQ,OAAO,CAAC,OAAO,EAAqC,CACzF,iCAAiC,CAClC;CAAG;AAEJ,8FAA8F;AAC9F,MAAM,OAAO,sBAAuB,SAAQ,MAAM,CAAC,WAAW,CAC5D,sCAAsC,CACvC,CAAC,wBAAwB,EAAE;IAC1B,OAAO,EAAE,MAAM,CAAC,cAAc;CAC/B,CAAC;CAAG"}

package/dist/error.d.ts

@@ -1,36 +1,54 @@
 import { Schema } from "effect";
 import { InstallationDiscoveryError } from "./installation.ts";
 import { AppPermissionError } from "./access.ts";
-/** The GitHub request that failed, shared by API, rate-limit, and response errors. */
-export declare const GitHubOperation: Schema.Literals<readonly ["create-repository-label", "discover-installation", "fetch-item-labels", "fetch-issue-snapshot", "fetch-pull-request-snapshot", "list-installation-repositories", "list-repository-labels", "mint-installation-token", "mint-worker-token", "poll-repository-changes", "update-item-labels"]>;
+/** The GitHub request that failed, used by API, rate-limit, and response errors. */
+export declare const GitHubOperation: Schema.Literals<readonly ["create-repository-label", "discover-installation", "fetch-base-ref-head", "fetch-item-labels", "fetch-issue-snapshot", "fetch-item-timeline", "fetch-pull-request-snapshot", "find-missing-issues", "list-installation-repositories", "list-repository-labels", "mint-installation-token", "mint-worker-token", "poll-repository-changes", "read-bot-account", "update-item-labels"]>;
 export type GitHubOperation = typeof GitHubOperation.Type;
 declare const GitHubApiError_base: Schema.Class<GitHubApiError, Schema.TaggedStruct<"GitHubApiError", {
-    readonly operation: Schema.Literals<readonly ["create-repository-label", "discover-installation", "fetch-item-labels", "fetch-issue-snapshot", "fetch-pull-request-snapshot", "list-installation-repositories", "list-repository-labels", "mint-installation-token", "mint-worker-token", "poll-repository-changes", "update-item-labels"]>;
+    readonly operation: Schema.Literals<readonly ["create-repository-label", "discover-installation", "fetch-base-ref-head", "fetch-item-labels", "fetch-issue-snapshot", "fetch-item-timeline", "fetch-pull-request-snapshot", "find-missing-issues", "list-installation-repositories", "list-repository-labels", "mint-installation-token", "mint-worker-token", "poll-repository-changes", "read-bot-account", "update-item-labels"]>;
     readonly status: Schema.Option<Schema.Int>;
     readonly message: Schema.NonEmptyString;
 }>, import("effect/Cause").YieldableError>;
-/** A failed GitHub request, with an HTTP status when a response was received. */
+/** A failed GitHub request, with the HTTP status if a response was received. */
 export declare class GitHubApiError extends GitHubApiError_base {
 }
 declare const GitHubRateLimitError_base: Schema.Class<GitHubRateLimitError, Schema.TaggedStruct<"GitHubRateLimitError", {
-    readonly operation: Schema.Literals<readonly ["create-repository-label", "discover-installation", "fetch-item-labels", "fetch-issue-snapshot", "fetch-pull-request-snapshot", "list-installation-repositories", "list-repository-labels", "mint-installation-token", "mint-worker-token", "poll-repository-changes", "update-item-labels"]>;
+    readonly operation: Schema.Literals<readonly ["create-repository-label", "discover-installation", "fetch-base-ref-head", "fetch-item-labels", "fetch-issue-snapshot", "fetch-item-timeline", "fetch-pull-request-snapshot", "find-missing-issues", "list-installation-repositories", "list-repository-labels", "mint-installation-token", "mint-worker-token", "poll-repository-changes", "read-bot-account", "update-item-labels"]>;
     readonly retryAt: Schema.DateTimeUtc;
     readonly message: Schema.NonEmptyString;
 }>, import("effect/Cause").YieldableError>;
-/** GitHub deferred the request until retryAt; callers can schedule a later attempt. */
+/** The error when GitHub defers the request until `retryAt`. */
 export declare class GitHubRateLimitError extends GitHubRateLimitError_base {
 }
 declare const InvalidGitHubResponseError_base: Schema.Class<InvalidGitHubResponseError, Schema.TaggedStruct<"InvalidGitHubResponseError", {
-    readonly operation: Schema.Literals<readonly ["create-repository-label", "discover-installation", "fetch-item-labels", "fetch-issue-snapshot", "fetch-pull-request-snapshot", "list-installation-repositories", "list-repository-labels", "mint-installation-token", "mint-worker-token", "poll-repository-changes", "update-item-labels"]>;
+    readonly operation: Schema.Literals<readonly ["create-repository-label", "discover-installation", "fetch-base-ref-head", "fetch-item-labels", "fetch-issue-snapshot", "fetch-item-timeline", "fetch-pull-request-snapshot", "find-missing-issues", "list-installation-repositories", "list-repository-labels", "mint-installation-token", "mint-worker-token", "poll-repository-changes", "read-bot-account", "update-item-labels"]>;
     readonly message: Schema.NonEmptyString;
-    /** What made the response invalid: the decode path, the missing field, or the GraphQL errors. */
+    /** The decode path, missing field, or GraphQL errors. */
     readonly detail: Schema.NonEmptyString;
 }>, import("effect/Cause").YieldableError>;
-/** GitHub returned a response that cannot be decoded or is missing required content. */
+/** The error when a GitHub response can't be decoded or lacks required content. */
 export declare class InvalidGitHubResponseError extends InvalidGitHubResponseError_base {
 }
-/** Failures from discovering installation access or making an authenticated GitHub request. */
+declare const GitHubItemNotFoundError_base: Schema.Class<GitHubItemNotFoundError, Schema.TaggedStruct<"GitHubItemNotFoundError", {
+    readonly operation: Schema.Literals<readonly ["create-repository-label", "discover-installation", "fetch-base-ref-head", "fetch-item-labels", "fetch-issue-snapshot", "fetch-item-timeline", "fetch-pull-request-snapshot", "find-missing-issues", "list-installation-repositories", "list-repository-labels", "mint-installation-token", "mint-worker-token", "poll-repository-changes", "read-bot-account", "update-item-labels"]>;
+    readonly item: Schema.Int;
+    readonly message: Schema.NonEmptyString;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The error when the repository has no Item with this number because it was deleted,
+ * transferred, or is no longer readable by the App. The repository itself responded.
+ */
+export declare class GitHubItemNotFoundError extends GitHubItemNotFoundError_base {
+}
+/** The errors from installation discovery or an authenticated GitHub request. */
 export declare const GitHubAppError: Schema.Union<readonly [typeof InstallationDiscoveryError, typeof AppPermissionError, typeof GitHubApiError, typeof GitHubRateLimitError, typeof InvalidGitHubResponseError]>;
 export type GitHubAppError = typeof GitHubAppError.Type;
+/**
+ * Returns whether GitHub gave a definite response that a retry won't change: no usable
+ * installation, a missing permission, or a 4xx status other than 408 and 429 (for example, 422
+ * for an ungranted permission or 403 for a suspended installation). Send failures, server
+ * errors, rate limits, and responses that break GitHub's API contract aren't refusals.
+ */
+export declare const isRefusal: (error: GitHubAppError) => boolean;
 export {};
 //# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,sFAAsF;AACtF,eAAO,MAAM,eAAe,yTAY1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAC;;;;;;AAE1D,iFAAiF;AACjF,qBAAa,cAAe,SAAQ,mBAMlC;CAAG;;;;;;AAEL,uFAAuF;AACvF,qBAAa,oBAAqB,SAAQ,yBAMxC;CAAG;;;;IAQH,iGAAiG;;;AANnG,wFAAwF;AACxF,qBAAa,0BAA2B,SAAQ,+BAO9C;CAAG;AAEL,+FAA+F;AAC/F,eAAO,MAAM,cAAc,8KAMzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAC"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC/C,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,oFAAoF;AACpF,eAAO,MAAM,eAAe,kZAgB1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAC;;;;;;AAE1D,gFAAgF;AAChF,qBAAa,cAAe,SAAQ,mBAMlC;CAAG;;;;;;AAEL,gEAAgE;AAChE,qBAAa,oBAAqB,SAAQ,yBAMxC;CAAG;;;;IAQH,yDAAyD;;;AAN3D,mFAAmF;AACnF,qBAAa,0BAA2B,SAAQ,+BAO9C;CAAG;;;;;;AAEL;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,4BAM3C;CAAG;AAEL,iFAAiF;AACjF,eAAO,MAAM,cAAc,8KAMzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAC;AAExD;;;;;GAKG;AACH,eAAO,MAAM,SAAS,UAAW,cAAc,KAAG,OAQ9C,CAAC"}

package/dist/error.js

@@ -1,43 +1,57 @@
-import { Schema } from "effect";
+import { Match, Option, Schema } from "effect";
 import { InstallationDiscoveryError } from "./installation.js";
 import { AppPermissionError } from "./access.js";
-/** The GitHub request that failed, shared by API, rate-limit, and response errors. */
+/** The GitHub request that failed, used by API, rate-limit, and response errors. */
 export const GitHubOperation = Schema.Literals([
     "create-repository-label",
     "discover-installation",
+    "fetch-base-ref-head",
     "fetch-item-labels",
     "fetch-issue-snapshot",
+    "fetch-item-timeline",
     "fetch-pull-request-snapshot",
+    "find-missing-issues",
     "list-installation-repositories",
     "list-repository-labels",
     "mint-installation-token",
     "mint-worker-token",
     "poll-repository-changes",
+    "read-bot-account",
     "update-item-labels",
 ]);
-/** A failed GitHub request, with an HTTP status when a response was received. */
+/** A failed GitHub request, with the HTTP status if a response was received. */
 export class GitHubApiError extends Schema.TaggedError("@usine/github/GitHubApiError")("GitHubApiError", {
     operation: GitHubOperation,
     status: Schema.Option(Schema.Int),
     message: Schema.NonEmptyString,
 }) {
 }
-/** GitHub deferred the request until retryAt; callers can schedule a later attempt. */
+/** The error when GitHub defers the request until `retryAt`. */
 export class GitHubRateLimitError extends Schema.TaggedError("@usine/github/GitHubRateLimitError")("GitHubRateLimitError", {
     operation: GitHubOperation,
     retryAt: Schema.DateTimeUtc,
     message: Schema.NonEmptyString,
 }) {
 }
-/** GitHub returned a response that cannot be decoded or is missing required content. */
+/** The error when a GitHub response can't be decoded or lacks required content. */
 export class InvalidGitHubResponseError extends Schema.TaggedError("@usine/github/InvalidGitHubResponseError")("InvalidGitHubResponseError", {
     operation: GitHubOperation,
     message: Schema.NonEmptyString,
-    /** What made the response invalid: the decode path, the missing field, or the GraphQL errors. */
+    /** The decode path, missing field, or GraphQL errors. */
     detail: Schema.NonEmptyString,
 }) {
 }
-/** Failures from discovering installation access or making an authenticated GitHub request. */
+/**
+ * The error when the repository has no Item with this number because it was deleted,
+ * transferred, or is no longer readable by the App. The repository itself responded.
+ */
+export class GitHubItemNotFoundError extends Schema.TaggedError("@usine/github/GitHubItemNotFoundError")("GitHubItemNotFoundError", {
+    operation: GitHubOperation,
+    item: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)),
+    message: Schema.NonEmptyString,
+}) {
+}
+/** The errors from installation discovery or an authenticated GitHub request. */
 export const GitHubAppError = Schema.Union([
     InstallationDiscoveryError,
     AppPermissionError,
@@ -45,4 +59,17 @@ export const GitHubAppError = Schema.Union([
     GitHubRateLimitError,
     InvalidGitHubResponseError,
 ]);
+/**
+ * Returns whether GitHub gave a definite response that a retry won't change: no usable
+ * installation, a missing permission, or a 4xx status other than 408 and 429 (for example, 422
+ * for an ungranted permission or 403 for a suspended installation). Send failures, server
+ * errors, rate limits, and responses that break GitHub's API contract aren't refusals.
+ */
+export const isRefusal = (error) => Match.valueTags(error, {
+    InstallationDiscoveryError: () => true,
+    AppPermissionError: () => true,
+    GitHubApiError: ({ status }) => Option.exists(status, (code) => code >= 400 && code < 500 && code !== 408 && code !== 429),
+    GitHubRateLimitError: () => false,
+    InvalidGitHubResponseError: () => false,
+});
 //# sourceMappingURL=error.js.map

package/dist/error.js.map

@@ -1 +1 @@
-{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,sFAAsF;AACtF,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC7C,yBAAyB;IACzB,uBAAuB;IACvB,mBAAmB;IACnB,sBAAsB;IACtB,6BAA6B;IAC7B,gCAAgC;IAChC,wBAAwB;IACxB,yBAAyB;IACzB,mBAAmB;IACnB,yBAAyB;IACzB,oBAAoB;CACrB,CAAC,CAAC;AAGH,iFAAiF;AACjF,MAAM,OAAO,cAAe,SAAQ,MAAM,CAAC,WAAW,CACpD,8BAA8B,CAC/B,CAAC,gBAAgB,EAAE;IAClB,SAAS,EAAE,eAAe;IAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC,cAAc;CAC/B,CAAC;CAAG;AAEL,uFAAuF;AACvF,MAAM,OAAO,oBAAqB,SAAQ,MAAM,CAAC,WAAW,CAC1D,oCAAoC,CACrC,CAAC,sBAAsB,EAAE;IACxB,SAAS,EAAE,eAAe;IAC1B,OAAO,EAAE,MAAM,CAAC,WAAW;IAC3B,OAAO,EAAE,MAAM,CAAC,cAAc;CAC/B,CAAC;CAAG;AAEL,wFAAwF;AACxF,MAAM,OAAO,0BAA2B,SAAQ,MAAM,CAAC,WAAW,CAChE,0CAA0C,CAC3C,CAAC,4BAA4B,EAAE;IAC9B,SAAS,EAAE,eAAe;IAC1B,OAAO,EAAE,MAAM,CAAC,cAAc;IAC9B,iGAAiG;IACjG,MAAM,EAAE,MAAM,CAAC,cAAc;CAC9B,CAAC;CAAG;AAEL,+FAA+F;AAC/F,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,KAAK,CAAC;IACzC,0BAA0B;IAC1B,kBAAkB;IAClB,cAAc;IACd,oBAAoB;IACpB,0BAA0B;CAC3B,CAAC,CAAC"}
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC/C,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,oFAAoF;AACpF,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC7C,yBAAyB;IACzB,uBAAuB;IACvB,qBAAqB;IACrB,mBAAmB;IACnB,sBAAsB;IACtB,qBAAqB;IACrB,6BAA6B;IAC7B,qBAAqB;IACrB,gCAAgC;IAChC,wBAAwB;IACxB,yBAAyB;IACzB,mBAAmB;IACnB,yBAAyB;IACzB,kBAAkB;IAClB,oBAAoB;CACrB,CAAC,CAAC;AAGH,gFAAgF;AAChF,MAAM,OAAO,cAAe,SAAQ,MAAM,CAAC,WAAW,CACpD,8BAA8B,CAC/B,CAAC,gBAAgB,EAAE;IAClB,SAAS,EAAE,eAAe;IAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC,cAAc;CAC/B,CAAC;CAAG;AAEL,gEAAgE;AAChE,MAAM,OAAO,oBAAqB,SAAQ,MAAM,CAAC,WAAW,CAC1D,oCAAoC,CACrC,CAAC,sBAAsB,EAAE;IACxB,SAAS,EAAE,eAAe;IAC1B,OAAO,EAAE,MAAM,CAAC,WAAW;IAC3B,OAAO,EAAE,MAAM,CAAC,cAAc;CAC/B,CAAC;CAAG;AAEL,mFAAmF;AACnF,MAAM,OAAO,0BAA2B,SAAQ,MAAM,CAAC,WAAW,CAChE,0CAA0C,CAC3C,CAAC,4BAA4B,EAAE;IAC9B,SAAS,EAAE,eAAe;IAC1B,OAAO,EAAE,MAAM,CAAC,cAAc;IAC9B,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC,cAAc;CAC9B,CAAC;CAAG;AAEL;;;GAGG;AACH,MAAM,OAAO,uBAAwB,SAAQ,MAAM,CAAC,WAAW,CAC7D,uCAAuC,CACxC,CAAC,yBAAyB,EAAE;IAC3B,SAAS,EAAE,eAAe;IAC1B,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;IACxD,OAAO,EAAE,MAAM,CAAC,cAAc;CAC/B,CAAC;CAAG;AAEL,iFAAiF;AACjF,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,KAAK,CAAC;IACzC,0BAA0B;IAC1B,kBAAkB;IAClB,cAAc;IACd,oBAAoB;IACpB,0BAA0B;CAC3B,CAAC,CAAC;AAGH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAqB,EAAW,EAAE,CAC1D,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE;IACrB,0BAA0B,EAAE,GAAG,EAAE,CAAC,IAAI;IACtC,kBAAkB,EAAE,GAAG,EAAE,CAAC,IAAI;IAC9B,cAAc,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAC7B,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG,IAAI,IAAI,GAAG,GAAG,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,CAAC;IAC5F,oBAAoB,EAAE,GAAG,EAAE,CAAC,KAAK;IACjC,0BAA0B,EAAE,GAAG,EAAE,CAAC,KAAK;CACxC,CAAC,CAAC"}