onetaskgraph_github_projects/

lib.rs

//! A stateless onetaskgraph source over one GitHub Projects v2 board.
//!
//! **A board is a container of projects, not a project.** Its own `title`,
//! `shortDescription` and `readme` are never read as an item's fields and are never
//! written: nothing in this source can rename the board a user configured.
//!
//! **A project is an issue and its tasks are that issue's sub-issues.** GitHub's schema
//! decides that: `Issue` exposes `parent`, `subIssues` and `subIssuesSummary`, and
//! `DraftIssue` exposes none of them. Creating an issue needs a `repositoryId`, and a
//! board has none, so a write without [`GitHubProjectsConfig::repository`] is refused
//! naming the field — but that repository is the *fallback*, not the home of every item.
//!
//! <!-- llmlint: ignore-block[contracts_have_one_source_or_a_drift_gate] The rule's one
//! executable source is `GitHubProjectsSource::creation_target`; this is where a reader of
//! the module meets it, and `tests/plugin.rs` drives every arm below against the loopback
//! board and asserts on `createIssue`'s own `repositoryId`, so the prose cannot outlive a
//! change to the rule. -->
//! **Which repository an issue is created in is decided by the item's own `repositories`
//! field, under one rule.** Exactly one entry names the repository the issue is created in:
//! a task issue is where a person finds the work from the repository it changes, and one
//! filed in a board's nominated repository is invisible from every other. Zero entries, or
//! two or more, name none, so a task's or a document's issue is created in the repository
//! its parent project's issue lives in — read from the board, or from this process's own
//! record of a project it created earlier in the same command — and a project's issue, or
//! a task or document written with no parent, is created in the configured `repository:`.
//! What that rule refuses, it refuses before `createIssue`, so no issue is half-created. An
//! existing issue is never moved: the update path leaves the issue where it is and records
//! the list in the metadata slot when it differs, so the read side's derivation and the
//! creation rule agree by construction.
//! <!-- llmlint: ignore-end[contracts_have_one_source_or_a_drift_gate] -->
//!
//! **A document is an ordinary issue whose title begins [`DESIGN_TITLE_PREFIX`].** A
//! board has no document type and nothing but issues to hold one in, so the title is the
//! discriminator and it is the whole of it. The title this source *reports* is the one a
//! person wrote, with the prefix taken off — the same way the metadata slot is taken off
//! the body so `content` is what the person wrote — and writing a document puts the prefix
//! back, so a round trip returns the title that went in.
//!
//! **Telling a document from a project from a task.** The design prefix is read **first**:
//! a document is never a project and never a task, whatever sub-issues it has or does not
//! have. Only then does the rest apply — a board issue is a project when *either* it has
//! sub-issues *or* it carries [`ItemKind::METADATA_KEY`]; otherwise it is a task. A
//! sub-issue is always a task, whatever it carries. The marker is sufficient and never
//! necessary: it is what makes an *empty* project — the state a project copy passes
//! through between creating the project and filing its first task — readable as a
//! project, while the sub-issue arm lets a person author a project on the board by hand
//! with no knowledge of this product's metadata at all. Reading the prefix later than the
//! sub-issue rule would make a design issue with no sub-issues an empty project, which is
//! exactly the state that rule exists to catch. Pull requests are neither a project nor a
//! task nor a document and are ignored.
//!
//! **A task's comments are its issue's comments.** They are read off `Issue.comments` and
//! written with `addComment`, `updateIssueComment` and `deleteIssueComment`, and a comment's
//! id is GitHub's own node id for the `IssueComment`. Two things GitHub decides are refused
//! rather than papered over: a board **draft** is not an issue and has no comments at all, so
//! a comment call on one is refused rather than answered with an empty page; and GitHub signs
//! every comment as the account the token belongs to, so a comment handed an author of its
//! own is refused rather than posted under another name. GitHub's comment mutations take the
//! comment's id and nothing else, so an edit or a delete first reads which issue that comment
//! is on, and a comment on some other issue is one this task does not have.
//!
//! **Where an entity is, is a link.** Every project, task and document this source reports
//! carries a [`Location::Url`] naming the issue's own web address — the same address the
//! `url` field already reports, in the shape that says a reader can open it. That is the
//! contrast the location contract exists for: a reader holding an entity from this source
//! is handed something to link to and one holding an entity from a folder of Markdown is
//! handed a path, and neither has to know which plugin answered. It does not replace or
//! derive from `url`; that field goes on reporting what it always reported.
//!
//! **Where metadata lives.** Short typed things go to typed fields and native relations:
//! status to the board's `Status` single-select and the issue's own state, the copy
//! origin to a source-owned `onetaskgraph.origin` text field, and dependencies to
//! `blockedBy` and to sub-issue links. Unbounded caller JSON goes in a trailing
//! `<!-- onetaskgraph.metadata ... -->` comment at the end of the issue body — the same
//! encoding `docs/metadata.md` settles for Linear, not a second one. A ProjectV2 text
//! field is length-bounded and `shortDescription` is capped at 300 characters, which is
//! why neither can hold a caller's own prose. Setting one caller key on its own — on a task,
//! a project or a document alike — is one update of the issue body that changes that slot
//! and not one byte outside it, and it is not sent at all when the key already holds the
//! value.
//!
// llmlint: ignore-block[contracts_have_one_source_or_a_drift_gate] This public module documentation is a required user-facing description; the loopback plugin tests and shared live journey drive StatusMapping resolution, both mutations, and observed read-back together.
//! **Status.** `status_mapping` is per-instance configuration from a status category to
//! `null` or a board `Status` option name. `done` selects its mapped option and closes the
//! issue as `COMPLETED`; `cancelled` selects its mapped option and closes it as
//! `NOT_PLANNED`. Every open category reopens a closed issue before selecting its option.
//! A missing mapped option refuses the write before either representation changes. Reads
//! give a closed issue's reason precedence over its option, while an open issue's option
//! decides its category. The guarded [`GitHubProjectsSource::status_options`] operation is
//! the one path here that calls `updateProjectV2Field`: GitHub replaces the whole option
//! list, so it preserves every existing option id and verifies the field and item
//! assignments immediately afterwards. It counts a terminal category's mapped option as
//! configured, because a terminal write refuses without it. No ordinary source read or
//! write calls that mutation, whose
//! `singleSelectOptions` *overwrites* a field's option set, so no addition is additive
//! and a mistake destroys every item's status. A status this board cannot represent is a
//! refusal naming the status and the instance instead.
//!
//! `unknown` is disabled by default because this source cannot preserve an open-ended
//! status word: it writes an existing board option and never
//! creates an option. An operator may map `unknown` to one existing option, in which case
//! every unknown word lands on that option and reads back as `unknown` under the option's
//! name. This differs from `local-md`, which writes and reads the original word itself.
//!
//! The shipped terminal options are exactly `done: Done` and `cancelled: Cancelled`.
//! `done` also closes the issue because GitHub derives `subIssuesSummary.completed`
//! and the board's own `Sub-issues progress` field from closed sub-issues: a plan whose
//! finished tasks were only moved to a "Done" column would read 0% complete forever.
// llmlint: ignore-end[contracts_have_one_source_or_a_drift_gate]
//!
//! # What this source declares, field by field
//!
//! One verdict per field of [`Capabilities`], and what `Native` means when this source
//! says it. *Proven* means a shared journey drives it against the real
//! binary over this source's own row in `crates/onetaskgraph/tests/e2e/fixtures.rs`, and
//! `every_row_declares_exactly_what_its_plugin_reports` is what keeps this list and
//! [`capabilities`](TaskSource::capabilities) from parting.
//!
//! | Field | Verdict |
//! | --- | --- |
//! | `projects` | **Supported and proven,** and the one predicate here that is pushed down rather than applied in process: a task's project is the issue it is a sub-issue of, so a listing scoped to one *asks that issue* for its own sub-issues. This is the field that was declared and then not applied, which silently returned another project's tasks. |
//! | `documents` | **Supported and proven.** A board holds issues, so a document is one: the issue whose title begins [`DESIGN_TITLE_PREFIX`]. Reads, filters and paging answer on exactly the terms a task read does, and a write puts the prefix back. |
//! | `comments` | **Supported and proven,** over the task issue's own comment connection, oldest first and paged by GitHub's own cursor; added, edited and removed through GitHub's comment mutations, paced as every other mutation is. A draft item has no comments on GitHub and is refused, and so is an author, because GitHub records the signed-in account as every comment's author. |
//! | `orphan_tasks` | **Supported and proven.** A task issue with no `parent` is in no project. |
//! | `filter_by_label` | **Supported and proven,** over the issue's own labels. |
//! | `filter_by_status` | **Supported and proven,** over the board's `Status` option and the issue's open or closed state, through this instance's own `status_mapping`. |
//! | `search_title` | **Supported and proven,** over `Issue.title`. |
//! | `search_content` | **Supported and proven,** over the visible body — the trailing metadata comment is not part of it. |
//! | `task_dependencies` | **Supported and proven,** in both directions: `blockedBy` and `blocking`. |
//! | `project_dependencies` | **Supported and proven,** in both directions, over the same two connections, because a project here is an issue. |
//! | `max_page_size` | **Supported and proven.** [`MAX_PAGE_SIZE`], GitHub's own connection maximum. |
//!
//! Nothing here is unsupported. `documents` and `comments` are not predicates — they say this
//! source has documents and that its tasks have comments, both of which hold — and the three
//! facts behind the uniform `Native` on the
//! predicates beside it are recorded below rather than re-derived, because a reader who
//! takes `Native` to mean *the remote service filters* will read that uniformity as a
//! lie.
//!
//! First, the plugin contract defines `Support::Native` as *the source applies this
//! predicate itself*, and says nothing about where it applies it. What the declaration
//! promises the engine is capability rule 1 — a predicate declared `Native` **is** applied
//! — so that the engine may push it down and apply nothing of its own.
//!
//! Second, this source can keep that promise for every predicate at no additional API
//! cost, because whichever of the three reads below answers a query has already read every
//! item that query could keep before it filters anything. Filtering those items is
//! in-process work over data already in hand.
//!
//! Third, no predicate but `projects` could be pushed into the API even if that were
//! wanted, and `projects` is pushed down: `ProjectV2.items` takes `first` and `after` and
//! offers no filter argument of any kind, GitHub's issue search offers no qualifier for a
//! label set, a status column or a substring of a body, and its title qualifier matches
//! tokens where this source — and the local Markdown source beside it — match substrings,
//! so pushing a search down would silently *narrow* the answer. What a project filter has
//! instead is a relationship: a project's tasks are that issue's sub-issues, and asking
//! the issue for them is both cheaper and exact. So there is one predicate this source
//! applies by asking a narrower question, six it applies in process, and none it is unable
//! to apply. Declaring one `Unsupported` would make the engine compensate for work this
//! source has already done, and declaring `projects` native while ignoring the filter
//! (which this source once did) silently returns another project's tasks, because the
//! engine trusts the declaration and applies nothing locally.
//!
//! # The three ways this source reaches an item, and what each costs
//!
//! A board read is charged for what its *nested* connections could return rather than for
//! what was asked, so one whole-board read costs the same whether the question was about
//! one project or about all of them. That is why a question about one project is never
//! answered by reading the board:
//!
//! | The question | What is sent | What it costs |
//! | --- | --- | --- |
//! | one item, by its own id | [`graphql::ISSUE`] — `node(id:)` — and, when that node is a board draft, [`graphql::DRAFT`] — the draft and the one board item it is | the item |
//! | the board's own id and field definitions, for a write whose item does not carry them | [`graphql::BOARD_FIELDS`] — the board's `id` and `fields`, and no `items` | the board's fields |
//! | one project's tasks or documents | [`graphql::SUB_ISSUES`] — that issue's own `subIssues` | that project |
//! | which projects this board holds | [`graphql::SEARCH_ISSUES`] — an issue search scoped to the board | the board's issues, without their board items |
//! | every task, every document, every label | [`graphql::BOARD`] — the board's own `items` — **and** [`graphql::SEARCH_ISSUES`], because neither enumeration of a board is complete alone; see [`GitHubProjectsSource::board`] | the board, twice over |
//! | which board item one issue is, past the page that came with it | [`graphql::ISSUE_BOARD_ITEMS`] — that issue's own `projectItems` | one issue's memberships |
//!
//! The board half of an issue — its board item's id, its `Status` option and this
//! source's origin text field — rides along on `Issue.projectItems` in the first three, so
//! an item reached any of those ways resolves through the same
//! [`GitHubProjectsSource::resolve`] the board walk uses and reports the same title, the
//! same status, the same labels and the same qualified id. That connection comes back a
//! *page* at a time, at `BOARD_ITEMS_PAGE_SIZE`, so the entry for this board is looked for
//! on the page in hand and — only if that page reports more of the connection — in the
//! last row's read of that one issue's memberships, resumed from the page's own cursor and
//! walked to exhaustion. An issue with no entry for *this* board is not this source's to
//! report, which is what keeps an id naming another repository's issue from being answered
//! as an item of this board; and because the page is where the search starts rather than
//! where it ends, that answer is one about a connection read to exhaustion and never about
//! an unread page. Nothing costs the extra read but an issue on more boards than a page
//! holds: an issue this board really does not hold reports no next page, so its
//! memberships are already exhausted where they arrived.
//!
//! **No document here selects the board's own `Labels` field, and nothing is lost by
//! that.** An item's labels are read from its content alone, wherever that content is
//! reached: the three documents above select `Issue.labels` on the fragment, and
//! [`graphql::BOARD`] selects the same connection on the `... on Issue` arm of its
//! `content`. A board's `Labels` field is not one anybody fills in: it is a built-in
//! `ProjectV2FieldType`, it is absent from `ProjectV2CustomFieldType` so no project can
//! create one, and `ProjectV2FieldValue` — the whole of what
//! `updateProjectV2ItemFieldValue` accepts — offers no way to write one. So GitHub derives
//! it from the content, for every content type it exists on, and there is nothing it can
//! hold that the content does not already say: for an `Issue` it *is* that issue's own
//! labels, so selecting it beside them unions a set with itself.
//!
//! **A draft loses nothing by that either**, which is the reasoning this paragraph once had
//! backwards. `DraftIssue` exposes no `labels` field, and by the three schema facts above
//! it cannot carry a board `Labels` value to be derived from one — so a draft has nothing
//! to select *and nothing to lose*, and reports no labels at all. A `PullRequest` item is
//! discarded by [`GitHubProjectsSource::resolve`] before labels are read. Both halves are
//! held to that by tests in `tests/plugin.rs`: the four ways an item is reached report one
//! label set, and that set is the fixture issue's own, by
//! `an_item_reports_the_same_labels_title_status_and_id_however_it_is_reached`; and a board
//! item whose content is a draft reports an empty set, by
//! `a_board_item_whose_content_is_a_draft_reports_no_labels_at_all`. The absence of the
//! selection is held over [`graphql::DOCUMENTS`] by
//! `no_document_selects_the_boards_own_labels_field`.
//!
//! The whole-board row is still the board's own item connection, and deliberately: a
//! **draft** board item is not an issue, so no search can list one, and the reads that have
//! to answer for the whole board are the ones whose cost is the board's size anyway.
//!
//! **A question about one item this source already names by id never lists the board.**
//! Whether that item is on this board, and what its board fields are, is answered by reading
//! that item — its own `Issue.projectItems`, walked to exhaustion by
//! [`GitHubProjectsSource::resolve_issue`], or a draft's own board item — and never by
//! looking for it in [`graphql::BOARD`]'s `items` or in a listing this command already
//! holds. That covers a write's destination, the project a new item is filed under, a
//! same-source far end a dependency names, a status write, the dependency slot a draft keeps,
//! and the delete that takes back an item a copy made. What such a write needs of the board
//! and the item does not carry — the board's id, the `Status` and origin field definitions —
//! comes from [`graphql::BOARD_FIELDS`], which reads no item at all. The reason is evidence,
//! not economy alone: `ProjectV2.items` is a projection that lags the membership GitHub
//! itself reports — an issue added with `addProjectV2ItemById` can be missing from it for
//! minutes. Scanning this host's 842-item board has refused a document copy and an update
//! even though the items' own reads named that board. A scan there gives the wrong answer
//! as well as paying for every page. So a `board.items` lookup does not belong on any of
//! those paths.
//!
//! **What a read may return is capped too, and that cap is on the document rather than on
//! the board.** GitHub limits the number of nodes **one query may return** to
//! [`NODE_COUNT_LIMIT`] and refuses a query above that before executing it: the answer is
//! an error naming the connection the count crossed at, not a slow or a partial result.
//! Every board this source reads is refused the same way, so no board is too big for these
//! documents and none is small enough to save one that is over.
//!
//! The count is arithmetic over the document's own text: each connection contributes the
//! `first:` it asks for, counts **multiply** down a nested path and **sum** across sibling
//! paths. Those are [GitHub's published rules][node-limits] and this workspace does not
//! restate them — `github-graphql-node-count` implements them, and
//! [`worst_case_node_count`] under [`largest_page_sizes`] is where every node count here
//! comes from. `every_document_this_source_sends_stays_under_githubs_node_limit`, in
//! `tests/node_count.rs`, recomputes every document in [`graphql::DOCUMENTS`] from that
//! same text on every run and fails naming any that reaches the limit — so a connection
//! added to a shared fragment is caught there rather than by GitHub.
//!
//! What decides those counts is the page sizes: [`MAX_PAGE_SIZE`] on the outer page,
//! `NESTED_PAGE_SIZE` on the connections hanging off one item, and
//! `BOARD_ITEMS_PAGE_SIZE` on the page of an issue's board memberships a read carries.
//! `$nestedFirst` is spent twice down one path of a board read, so that constant is
//! effectively squared there, which is why it is the one the limit is most sensitive to.
//! `BOARD_ITEMS_PAGE_SIZE` is small for a reason of its own, recorded beside it: what a
//! page of memberships misses is recovered by one further read rather than refused, so it
//! buys a bound every read pays for at the price of a request only a multi-board issue
//! pays.
//!
//! **`nodeCount` and `cost` are two numbers against two limits, and both are computed
//! offline here — per document, one document at a time.** `nodeCount` is the one above: the
//! most nodes one query may return, checked per query and bounded by [`NODE_COUNT_LIMIT`].
//! `cost` is rate-limit points, metered per hour across everything one credential does; it
//! is what the two limiters [`Limiter`] tells apart meter, and a document under
//! [`NODE_COUNT_LIMIT`] still says nothing about its price. [`worst_case_point_cost`] is
//! that second number, and `tests/point_cost.rs` pins every document in
//! [`graphql::DOCUMENTS`] at what it costs — there being no per-call point ceiling to hold
//! one under, the pin itself is the check. The credentialed lane reconciles both figures
//! against GitHub's own, off a probe it already sends.
//!
//! **What is pinned that way is a per-document price and never a session's.** The record in
//! `session-cost.md` measures the two quantities a whole session can be counted in offline —
//! **requests** and **worst-case nodes** — and neither is points. What one whole session
//! consumes of the hourly point allowance is observable only from a credentialed run's own
//! `x-ratelimit-*` headers, which is what [`accounting`] fills its per-budget figures from
//! and what `tests/live.rs` prints at the end of every run.
//!
//! [node-limits]: https://docs.github.com/en/graphql/overview/rate-limits-and-node-limits-for-the-graphql-api
//!
//! **Where a read-after-write guarantee comes from, since neither of GitHub's two
//! enumerations of a board can supply one alone.** Resolving a node id is strongly
//! consistent, so a read by id and a project's own sub-issues are already current. The
//! other two are not, and they are behind by different amounts and in different directions:
//!
//! - GitHub's **issue search** is an index and answers a write made moments ago with the
//!   value from before it — usually for a second or two.
//! - **`ProjectV2.items`** is a projection GitHub rebuilds behind the write, and an item put
//!   on a board with `addProjectV2ItemById` can be **absent** from it — not present with its
//!   content withheld, absent, with the connection walked to its own `hasNextPage: false` —
//!   for *minutes*, while `Issue.projectItems` names the same membership at once.
//!
//! That second one is a measurement rather than a caution. This repository's own
//! credentialed journey writes a project and waits for the board to report it, then writes a
//! task and waits for the same thing seconds later on the same board: the project wait is
//! answered through the search and converged in two or three attempts in each of three runs,
//! and the task wait is answered through `ProjectV2.items` and converged in none of them
//! inside thirty. Separately, an item added to a second and larger board was read back by
//! `Issue.projectItems` on that board's own id while every one of that connection's nine
//! pages, walked to exhaustion nine minutes after the add, did not name it. Reading a board
//! through the lagging one alone is what had a board read deny an issue that had certainly
//! landed on it.
//!
//! So [`GitHubProjectsSource::board`] is the **union** of both — each search result still
//! admitted only on this board's own strongly-consistent `Issue.projectItems`, and neither
//! enumeration dropped, because only `ProjectV2.items` lists a board draft and only the
//! search reports what the projection is behind on. What closes the last
//! gap, the one where both are behind, is [`GitHubProjectsSource::created`]: every read this
//! source answers is completed with what this process itself wrote, so an item created
//! seconds ago is reported whether or not GitHub has caught up. Nothing else is remembered,
//! nothing is written down, and the record dies with the process. **A wait that has to
//! observe GitHub's own data cannot be answered from that record** — which is why the
//! credentialed journey asks through a source built afresh, and why the union above rather
//! than a longer wait is what makes such a wait converge.
//!
//! Filtering happens before paging, so a page of a filtered result is a page of the
//! survivors rather than the survivors of a page. Label and text matching answer the same
//! question the same way the local Markdown source's do, so one cross-source expectation
//! holds for both.
//!
//! <!-- llmlint: ignore[contracts_have_one_source_or_a_drift_gate] The declaration itself
//! has one source, `capabilities`, and the note above is the reasoning behind it rather
//! than a second copy of it: without the three facts recorded here a reader takes the
//! uniform `Native` for a lie and reverts it. The drift gate on the declaration is this
//! crate's own capabilities test, which pins every field of it against a fully spelled-out
//! `Capabilities` literal — a struct with no `Default`, so a field added to the contract
//! fails to compile there rather than going unasserted. -->
//! The fixture-server tests above run wherever this crate is selected; the credentialed
//! lane runs in the same required check, beside them, and can fail it — it verifies the
//! current schema, then drives every field of the table above against the real board. It builds its own fixture there — two projects, one task filed under each,
//! one filed under neither, a label on one of the three and a closed status on another —
//! because that shape is what tells an honoured predicate from an ignored one: a board
//! holding a single project answers a project filter the same way whether or not this
//! source applies it, which is exactly how the defect above went unseen.
//!
//! That lane writes only to the board `GH_PROJECTS_OWNER` and `GH_PROJECTS_NUMBER` name,
//! and only into the repository `GH_PROJECTS_REPOSITORY` names, and skips — as it does
//! without `GH_PROJECTS_TOKEN` — when any of them is absent. Requiring both to be
//! nominated is what keeps a credentialed write lane off a board and a repository nobody
//! nominated; it never asks GitHub which project was updated most recently. Before it
//! starts, the lane also clears any item titled — and any repository label named — the way
//! it titles and names its own artifacts, which is self-healing after an interrupted run:
//! a process killed between its writes and its cleanup leaves artifacts the next run
//! removes.
//!
//! # What a session of requests costs, and where the report is
//!
//! This source records **every** request it sends into [`accounting::Accounting`], at
//! `send_once` — the one place a request leaves this crate, which is why a read path added
//! later is counted without anybody remembering to count it. That is the whole of what this
//! crate adds to the arrangement; [`accounting`] is where what a record carries, how a
//! session's spend is arrived at, and what it deliberately does not know are set out.
//!
//! What one whole session of the live journey costs, counted that way against this crate's
//! loopback fixture board, is written down in `session-cost.md` beside this crate — with the
//! reduction it came out of, and with what it does and does not say about rate-limit points.
//!
//! [`GitHubProjectsSource::accounting`] is the read: a snapshot to hold and compare, which
//! [`accounting::Session::report`] renders the session report from. It is on the ordinary
//! code path — no environment variable, no feature, no build configuration — because an
//! instrument nobody switches on measures nothing, and
//! [`Plugin::build_recording_into`] is how a caller making its own calls beside this
//! source's counts the whole session rather than this source's share. The credentialed lane
//! in `tests/live.rs` does exactly that, and prints the report at the end of every run,
//! passed or failed.
//!
//! **A live session refuses to start unless the account can afford it.** Before it does any
//! of the work it exists to do, the journey makes one request — `GET /rate_limit`, which
//! GitHub documents as not counting against the REST rate limit and which answers both of
//! its budgets at once — and starts only if, for each of them, what remains minus this
//! session's estimated cost is still at least
//! `onetaskgraph_live::RETAINED_BUFFER` — twenty per cent — of that budget's whole
//! allowance. A session that cannot **declines**: it did not run, so it is
//! neither a pass nor a failing assertion, and it says which budget was short, that budget's
//! limit, what remained, the estimate, the buffer and when it resets — then stops, without
//! waiting for the budget to come back. The estimate is derived offline from
//! `tests/fixtures/session-cost.txt` and a cost model stated in `tests/journey/budget.rs`,
//! which is also where the published rule that model rests on is cited; the accounting
//! above records the gate's own read like any other request, and
//! [`accounting::Session::report`] prints the estimate beside what the session really spent.
//!
//! **GitHub is the authority on both of its own numbers, and the credentialed lane goes and
//! asks it.** Everything above computes `nodeCount` and `cost` offline from a document's own
//! text, which is what lets it run on every platform and on a pull request from a fork with
//! no credential — and that is what actually stops a regression merging. But an offline
//! arithmetic can only ever agree with itself: if GitHub changes its rules, this workspace
//! goes on computing the old answer and nothing notices. So `tests/live.rs` reconciles them.
//! GitHub's schema exposes `rateLimit(dryRun: true)`, whose `nodeCount` is *"the maximum
//! number of nodes this query may return"* and whose `cost` is what that document would
//! spend, both for a document **without executing it**, and the lane asks it for every query
//! document this source sends, under the largest bindings this source sends, and fails when
//! GitHub's figure and [`worst_case_node_count`] or [`worst_case_point_cost`] disagree. A
//! mutation is skipped, because `rateLimit` is a field of `Query` and cannot be asked about
//! one; the offline pins still cover it. It records what those calls reported about the
//! account's own allowance, because whether asking is free is a thing to observe rather than
//! to assume. Two quantities, not one: [`NODE_COUNT_LIMIT`] bounds `nodeCount` per query,
//! and `cost` is metered against an hourly allowance the accounting above reads off a
//! credentialed run's own response headers.
//!
//! **GitHub has two rate limiters and this source is refused by both, so nothing here
//! treats them as one thing.** The primary budget is the hourly allowance `gh api
//! rate_limit` reports; the secondary limiter is a burst limiter over content-generating
//! requests, and *nothing* reports it. Which one refused decides the operator's next step,
//! so [`Limiter`] is a type rather than a detail, and it is what [`MIN_MUTATION_INTERVAL_MS`],
//! [`GitHubProjectsSource::board_cache`] and [`GitHubProjectsSource::graphql`] each answer
//! one part of.
#![deny(missing_docs)]

use std::collections::BTreeMap;
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};

use chrono::{DateTime, Utc};
use onetaskgraph_plugin_api::{
    Capabilities, Comment, CommentBody, Cursor, DependencyEdge, DependencyEndpoint, DependencyKind,
    DependencySupport, Direction, Document, DocumentQuery, Health, ItemKind, ItemWrite, Label,
    LabelFilter, Location, MetadataKey, Metering, NativeId, NewComment, Page, PageRequest, Project,
    ProjectFilter, ProjectQuery, Repository, SecretResolver, SourceError, SourceName, SourcePlugin,
    Status, StatusCategory, Support, Task, TaskQuery, TaskRef, TaskSource, TextFields, TextQuery,
    WriteSupport,
};
use reqwest::{Client, StatusCode, Url};
use schemars::{Schema, schema_for};
use secrecy::{ExposeSecret, SecretString};
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};

pub mod accounting;

use accounting::Accounting;

/// The registry name for this plugin.
pub const KIND: &str = "github-projects";
/// GitHub's maximum connection page size.
pub const MAX_PAGE_SIZE: u32 = 100;

/// The most nodes any one document this source sends may be asked to return.
///
/// GitHub's own published per-query ceiling, taken from
/// [`github_graphql_node_count::NODE_LIMIT`] rather than written out again here, so this
/// workspace cannot hold a stale copy of somebody else's number. A query above it is
/// **refused before it is executed**, whoever is asking and whatever board they are
/// asking about — so this is a bound on the documents rather than a budget that runs out.
///
/// This is `nodeCount`, the maximum number of nodes *one query may return*. It is not
/// `cost`, the rate-limit points a call spends against an hourly allowance shared by
/// everything the credential does — two numbers against two limits, and this constant
/// bounds only the first. The second is computed offline too, per document:
/// [`worst_case_point_cost`], pinned for every document in [`graphql::DOCUMENTS`] by
/// `tests/point_cost.rs`, and reconciled against GitHub's own `cost` by the credentialed
/// lane. There is no constant like this one to hold a price under, because points are an
/// hourly allowance rather than a per-call bound.
///
/// Neither is a session's price. What `session-cost.md` records of a whole session is its
/// **requests** and its **worst-case nodes**; what a whole session spends in points is
/// reported only by a credentialed run's own `x-ratelimit-*` headers, through
/// [`accounting`]. The module section on the three ways this source reaches an item says how
/// the count is arrived at, and which of the page sizes below decide it.
pub const NODE_COUNT_LIMIT: u64 = github_graphql_node_count::NODE_LIMIT;

/// Nested connection size for the connections that hang off one item.
///
/// It multiplies through every document that reaches an item under a page — the count
/// rules multiply down a nested path — so it is the constant [`NODE_COUNT_LIMIT`] is most
/// sensitive to. `tests/node_count.rs` is what holds the pair together: it recomputes
/// every document under these constants and fails naming any that reaches the limit, so
/// raising this is caught there rather than by GitHub.
const NESTED_PAGE_SIZE: u32 = 50;
/// How many of one issue's board memberships are read when an issue is reached directly.
///
/// An issue reached through a search or through its own node id carries its board half in
/// `Issue.projectItems`, and only the entry for *this* board is read. This connection sits
/// under a page of issues, so every point of it multiplies through the whole document and
/// is paid for whether or not any issue is on a second board — which is why it is
/// deliberately far smaller than [`NESTED_PAGE_SIZE`].
///
/// **Three, because what a page misses is now recovered rather than refused**, and the
/// recovery is what the value is chosen against. An issue whose entry for this board sits
/// past this page costs one further request — [`graphql::ISSUE_BOARD_ITEMS`], resumed from
/// that page's own cursor — so the value trades a bound every read pays for a request only
/// a multi-board issue pays. At one, a deployment whose issues commonly sit on two or more
/// boards would pay that request *per issue*, which is order N against the one page per
/// hundred issues a read costs today. At three it is only reached by an issue on four or
/// more boards at once, which keeps the recovery path exceptional rather than routine for
/// a plausible deployment.
const BOARD_ITEMS_PAGE_SIZE: u32 = 3;

pub use github_graphql_node_count::{NodeCountError, Variables};

/// The largest value this source can bind to each page-size variable its documents name.
///
/// Every `first:` in [`graphql`] reads one of these three, and each is capped at the
/// constant above it wherever a caller's own limit could reach it — `$first` at
/// [`MAX_PAGE_SIZE`], `$nestedFirst` at `NESTED_PAGE_SIZE`, `$boardItems` at
/// `BOARD_ITEMS_PAGE_SIZE`. So this is the worst case a caller can drive this source to,
/// not one configuration of it, which is what makes a bound computed under it a bound on
/// every read.
pub fn largest_page_sizes() -> Variables {
    Variables::from([
        ("first".to_owned(), MAX_PAGE_SIZE),
        ("nestedFirst".to_owned(), NESTED_PAGE_SIZE),
        ("boardItems".to_owned(), BOARD_ITEMS_PAGE_SIZE),
    ])
}

/// The most nodes `document` could be asked to return, by GitHub's published rules.
///
/// Computed offline from the document's own text under [`largest_page_sizes`] — no
/// network, no credential and no schema — by
/// [`github_graphql_node_count::node_count`], which is where the rules themselves live.
/// A document at or above [`NODE_COUNT_LIMIT`] is one GitHub refuses before executing, so
/// this is what a check holds every document in [`graphql::DOCUMENTS`] below.
///
/// # Errors
///
/// Returns the calculation's own [`NodeCountError`] when `document` does not parse, holds
/// no single operation, or binds a page size this source does not name — each of which is
/// a defect in the document rather than a number.
pub fn worst_case_node_count(document: &str) -> Result<u64, NodeCountError> {
    node_count(document, &largest_page_sizes())
}

/// The most rate-limit points one call of `document` could spend, by GitHub's published
/// rules.
///
/// Computed offline from the document's own text under [`largest_page_sizes`] — no
/// network, no credential and no schema — by
/// [`github_graphql_node_count::point_cost`], which is where the rules themselves live.
/// This is `cost`, metered **per hour** against the allowance one credential shares across
/// everything it does; it is not `nodeCount`, which is [`worst_case_node_count`] and is
/// bounded per query by [`NODE_COUNT_LIMIT`]. There is no per-call ceiling to hold this
/// under, so what `tests/point_cost.rs` does with it is pin every document in
/// [`graphql::DOCUMENTS`] at what it costs, and the credentialed lane reconciles those
/// figures against GitHub's own reported `cost`.
///
/// # Errors
///
/// Returns the calculation's own [`NodeCountError`] when `document` does not parse, holds
/// no single operation, or binds a page size this source does not name — each of which is
/// a defect in the document rather than a number.
pub fn worst_case_point_cost(document: &str) -> Result<u64, NodeCountError> {
    github_graphql_node_count::point_cost(document, &largest_page_sizes())
}

/// The most nodes `document` could be asked to return under `variables`.
///
/// [`worst_case_node_count`] is this under [`largest_page_sizes`], and the accounting in
/// [`accounting`] is this under the bindings one request really sent — one spelling of the
/// calculation, so a bound checked offline and a cost recorded at run time cannot come to
/// disagree. The rules themselves live in [`github_graphql_node_count::node_count`].
///
/// # Errors
///
/// Returns the calculation's own [`NodeCountError`] when `document` does not parse, holds
/// no single operation, or binds a page size `variables` does not name.
pub fn node_count(document: &str, variables: &Variables) -> Result<u64, NodeCountError> {
    github_graphql_node_count::node_count(document, variables)
}

/// The issue-title prefix that makes a board issue a document.
///
/// A GitHub Projects board has no document type — it holds issues — so the discriminator
/// is the title, and this is the whole of it: an issue whose title begins with these bytes
/// is a document and every other issue is the task or project the sub-issue rule makes it.
///
/// It is spelled **once**, here, and read rather than restated everywhere else — including
/// by the shared journeys, which take it from this constant so a board fixture cannot
/// drift from what this source reads. `docs/metadata.md` records the two consequences that
/// are not obvious from the bytes: the reported title has this prefix taken off, exactly
/// as the body's metadata slot is taken off `content`, and this prefix is read *before*
/// the sub-issue rule, so a design issue with no sub-issues is never an empty project.
pub const DESIGN_TITLE_PREFIX: &str = "DESIGN: ";

/// Exact GraphQL query documents issued by this plugin.
///
/// Keeping the production documents here lets the pinned-schema test validate the same
/// bytes that are sent to GitHub, rather than a test-only copy which could drift
/// independently. [`STATUS_OPTIONS_UPDATE`] is the sole document that may rewrite a board
/// field, and its guarded caller always supplies the complete existing option set with ids.
pub mod graphql {
    /// The board half of one item: the field values every document here reads it from.
    ///
    /// A macro for the same reason [`board_issue!`] below is one, a level further in. This
    /// selection is needed by that fragment, by [`BOARD`] under the board's own `items`,
    /// and by [`ISSUE_BOARD_ITEMS`] under a membership walk — and all three have to produce
    /// *the same value*, because
    /// [`GitHubProjectsSource::resolve`](super::GitHubProjectsSource) reads them through
    /// one path. Three spellings of it is what would drift, so there is one.
    ///
    /// The `Status` option and this source's own origin text field are the whole of it. It
    /// selects no `ProjectV2ItemFieldLabelValue`: GitHub derives that field from the item's
    /// content, so it holds nothing the content's own `labels` do not already say, and it
    /// would sit a label connection two page sizes deep.
    macro_rules! board_item_values {
        () => {
            r#"fieldValues(first:$nestedFirst){nodes{
          ... on ProjectV2ItemFieldSingleSelectValue{name field{
            ... on ProjectV2SingleSelectField{id name options{id name}}
          }}
          ... on ProjectV2ItemFieldTextValue{text field{... on ProjectV2Field{id name}}}
        }pageInfo{hasNextPage}}"#
        };
    }

    /// Everything this source reads about one issue, wherever it reaches that issue.
    ///
    /// A macro rather than a constant so the three documents below can `concat!` it: one
    /// spelling of these fields is what makes an issue read through the board-scoped
    /// search, through its own node id, and through its project's sub-issue relationship
    /// resolve to *the same* item, which is the whole of what
    /// [`GitHubProjectsSource::resolve_issue`](super::GitHubProjectsSource) relies on.
    ///
    /// `projectItems` is what carries the board half of an issue: the board item's own id
    /// and the [`board_item_values!`] above — the `Status` option and this source's origin
    /// text field — that a `ProjectV2.items` read used to carry. It is asked for on the
    /// issue rather than on the board, which is what makes the cost of a read proportional
    /// to what was asked for instead of to the board's size.
    ///
    /// It carries a *page* of that connection, at `BOARD_ITEMS_PAGE_SIZE`, and its
    /// `endCursor` is what [`ISSUE_BOARD_ITEMS`] resumes from when this board's entry is
    /// not on that page: a page here is where the search for the entry starts rather than
    /// where it ends.
    ///
    /// It does **not** select the board's `Labels` field value, and that is the whole of
    /// what keeps the three documents below under [`NODE_COUNT_LIMIT`](super::NODE_COUNT_LIMIT):
    /// a label connection there sits under `fieldValues` under `projectItems` under a page
    /// of issues, spending `$nestedFirst` twice down one path, and took
    /// [`SEARCH_ISSUES`] and [`SUB_ISSUES`] to 2,556,100 nodes against a limit of 500,000.
    /// No label is lost — this is a fragment `on Issue`, whose own `labels` are selected
    /// above, and that connection is where every label this source reports comes from. No
    /// document in this module selects the board field any longer, [`BOARD`] included; the
    /// module documentation records why nothing it could have held is lost.
    macro_rules! board_issue {
        () => {
            concat!(
                r#" fragment BoardIssue on Issue{__typename id number title body url createdAt updatedAt state stateReason(enableDuplicate:$duplicates) repository{nameWithOwner} parent{id} subIssuesSummary{total}
      labels(first:$nestedFirst){nodes{id name color}pageInfo{hasNextPage}}
      projectItems(first:$boardItems){nodes{id project{id number}
        "#,
                board_item_values!(),
                r#"}pageInfo{hasNextPage endCursor}}}"#
            )
        };
    }

    /// Every issue of one board, found by a search scoped to that board.
    ///
    /// This is how the projects a board holds are listed, and it selects no `items`
    /// connection on `ProjectV2`: the board is a *qualifier of the search* rather than a
    /// container walked page by page, so nothing nested inside a board item is paid for.
    /// Which of the issues it returns is a project is then read off `parent` — GitHub
    /// accepts `-has:parent` as a search qualifier and silently ignores it, so the
    /// discriminator has to be applied to the field, which is a scalar on the issue and
    /// costs nothing.
    pub const SEARCH_ISSUES: &str = concat!(
        r#"query($search:String!,$type:SearchType!,$first:Int!,$after:String,$nestedFirst:Int!,$boardItems:Int!,$duplicates:Boolean!){
      search(query:$search,type:$type,first:$first,after:$after){
        pageInfo{hasNextPage endCursor}
        nodes{__typename ...BoardIssue}
      }
    }"#,
        board_issue!()
    );

    /// One issue by its own node id, which is what a qualified id names here.
    ///
    /// Strongly consistent, unlike the search above: GitHub's issue search is an index and
    /// answers a write made moments ago with the value from before it, and resolving a node
    /// id does not.
    pub const ISSUE: &str = concat!(
        r#"query($id:ID!,$nestedFirst:Int!,$boardItems:Int!,$duplicates:Boolean!){
      node(id:$id){__typename ...BoardIssue}
    }"#,
        board_issue!()
    );

    /// One project's tasks: the sub-issues of the issue that project is.
    ///
    /// The work this costs is the project's own size. Nothing about it grows as the board
    /// gains projects, or as those projects gain tasks.
    pub const SUB_ISSUES: &str = concat!(
        r#"query($id:ID!,$first:Int!,$after:String,$nestedFirst:Int!,$boardItems:Int!,$duplicates:Boolean!){
      node(id:$id){__typename
        ... on Issue{subIssues(first:$first,after:$after){
          pageInfo{hasNextPage endCursor}
          nodes{__typename ...BoardIssue}
        }}}
    }"#,
        board_issue!()
    );

    /// Reads the board's fields and one page of its items.
    pub const BOARD: &str = concat!(
        r#"query($owner:String!,$number:Int!,$first:Int!,$after:String,$nestedFirst:Int!,$duplicates:Boolean!){
      owner:repositoryOwner(login:$owner){
        ... on ProjectV2Owner{projectV2(number:$number){...Board}}
      }
    } fragment Board on ProjectV2 { id title
      fields(first:$nestedFirst){nodes{
        ... on ProjectV2SingleSelectField{__typename id name options{id name}}
        ... on ProjectV2Field{__typename id name}
      }pageInfo{hasNextPage}}
      items(first:$first,after:$after){nodes{id "#,
        board_item_values!(),
        r#" content{
        ... on Issue{__typename id number title body url createdAt updatedAt state stateReason(enableDuplicate:$duplicates) repository{nameWithOwner} parent{id} subIssuesSummary{total} labels(first:$nestedFirst){nodes{id name color}pageInfo{hasNextPage}}}
        ... on PullRequest{__typename id}
        ... on DraftIssue{__typename id title body createdAt updatedAt}
      }} pageInfo{hasNextPage endCursor}}
    }"#
    );

    /// The board's own id and field definitions, and not one of its items.
    ///
    /// What a write needs of the board when the item it writes does not say: the id a field
    /// write and `addProjectV2ItemById` address, and the definitions of the `Status` and
    /// origin fields. It selects no `items`, so what it costs is the board's field list
    /// however many items the board holds — and it decides nothing about which items those
    /// are, which is the question a read of one item by its own id answers instead.
    ///
    /// The root is aliased `boardFields` rather than `owner`, so nothing counting the
    /// board's item reads by their root counts this one among them.
    pub const BOARD_FIELDS: &str = r#"query($owner:String!,$number:Int!,$nestedFirst:Int!){
      boardFields:repositoryOwner(login:$owner){
        ... on ProjectV2Owner{projectV2(number:$number){id
          fields(first:$nestedFirst){nodes{
            ... on ProjectV2SingleSelectField{__typename id name options{id name}}
            ... on ProjectV2Field{__typename id name}
          }pageInfo{hasNextPage}}
        }}
      }
    }"#;

    /// One board draft by its own node id, with the board item it sits in.
    ///
    /// A draft is not an issue, so [`ISSUE`] reaches it and reads nothing of it; this is the
    /// second read that answers it. `DraftIssue.projectV2Items` names the board item a draft
    /// is — GitHub links a draft to one item — with the same [`board_item_values!`] the
    /// issue fragment reads, so a draft reached by id resolves through the same resolver a
    /// board listing hands it to, and nothing has to list the board to find one.
    pub const DRAFT: &str = concat!(
        r#"query($id:ID!,$nestedFirst:Int!,$boardItems:Int!){
      node(id:$id){__typename ... on DraftIssue{id title body createdAt updatedAt
        projectV2Items(first:$boardItems){nodes{id project{id number}
        "#,
        board_item_values!(),
        r#"}pageInfo{hasNextPage endCursor}}}}
    }"#
    );

    /// One issue's board memberships alone, walked past the page a read of it carried.
    ///
    /// The recovery read behind [`GitHubProjectsSource::resolve_issue`](super::GitHubProjectsSource):
    /// every document above carries a *page* of `Issue.projectItems`, and an issue on more
    /// boards than that page holds may have this board's entry past its end. This asks that
    /// one issue for its memberships and nothing else — the caller already holds the issue —
    /// so an answer of "this board does not hold it" is only ever given about a connection
    /// read to exhaustion.
    ///
    /// It selects the board item's id, its project number and the same
    /// [`board_item_values!`] the fragment does, because what it produces is handed to the
    /// very same resolver: an issue recovered this way reports the same title, the same
    /// status, the same labels and the same qualified id as one whose entry was on the
    /// page.
    ///
    /// `$first` rather than `$boardItems`: this document reads one issue, so nothing
    /// multiplies through it and the membership connection can be walked at
    /// [`MAX_PAGE_SIZE`](super::MAX_PAGE_SIZE) — which is what keeps the recovery to one
    /// further request for any issue a person really keeps.
    pub const ISSUE_BOARD_ITEMS: &str = concat!(
        r#"query($id:ID!,$first:Int!,$after:String,$nestedFirst:Int!){
      node(id:$id){
        ... on Issue{projectItems(first:$first,after:$after){
          nodes{id project{id number}
        "#,
        board_item_values!(),
        r#"}
          pageInfo{hasNextPage endCursor}}}
      }
    }"#
    );
    /// Resolves the configured repository's node id, which creating an issue requires.
    pub const REPOSITORY: &str = r#"query($owner:String!,$name:String!){repository(owner:$owner,name:$name){id nameWithOwner}}"#;
    /// Reads both dependency directions for one issue, with each far end's own kind — and
    /// the issue's own body, which is where an edge to another source is recorded, so that
    /// half of a dependency read needs no second read of the issue or of the board.
    pub const ISSUE_DEPENDENCIES: &str = r#"query($id:ID!,$first:Int!,$after:String){node(id:$id){__typename
      ... on Issue{body
        blockedBy(first:$first,after:$after){nodes{...Related}pageInfo{hasNextPage endCursor}}
        blocking(first:$first,after:$after){nodes{...Related}pageInfo{hasNextPage endCursor}}
      }}} fragment Related on Issue{id title body parent{id} subIssuesSummary{total}}"#;
    /// Creates one issue in the configured repository.
    pub const CREATE_ISSUE: &str =
        r#"mutation($input:CreateIssueInput!){createIssue(input:$input){issue{id number url}}}"#;
    /// Puts an existing issue on the configured board.
    pub const ADD_TO_BOARD: &str = r#"mutation($input:AddProjectV2ItemByIdInput!){addProjectV2ItemById(input:$input){item{id}}}"#;
    /// Updates an issue's visible fields and its open or closed state in one call.
    pub const UPDATE_ISSUE: &str =
        r#"mutation($input:UpdateIssueInput!){updateIssue(input:$input){issue{id}}}"#;
    /// Updates an existing draft's user-visible fields.
    pub const UPDATE_DRAFT: &str = r#"mutation($input:UpdateProjectV2DraftIssueInput!){updateProjectV2DraftIssue(input:$input){draftIssue{id}}}"#;
    /// Updates a text or single-select value on one project item.
    pub const UPDATE_FIELD: &str = r#"mutation($input:UpdateProjectV2ItemFieldValueInput!){updateProjectV2ItemFieldValue(input:$input){projectV2Item{id}}}"#;
    /// Replaces a single-select field's options. Only the guarded status-options operation
    /// may use this document, because GitHub treats the input as the complete option list.
    pub const STATUS_OPTIONS_UPDATE: &str = r#"mutation($input:UpdateProjectV2FieldInput!){updateProjectV2Field(input:$input){projectV2Field{... on ProjectV2SingleSelectField{id options{id name color description}}}}}"#;
    /// A fresh snapshot of the Status field and every board item's assignment.
    pub const STATUS_OPTIONS_SNAPSHOT: &str = r#"query($owner:String!,$number:Int!,$first:Int!,$after:String,$nestedFirst:Int!){owner:repositoryOwner(login:$owner){... on ProjectV2Owner{projectV2(number:$number){id fields(first:$nestedFirst){nodes{... on ProjectV2SingleSelectField{id name options{id name color description}}}pageInfo{hasNextPage}} items(first:$first,after:$after){nodes{id fieldValues(first:$nestedFirst){nodes{... on ProjectV2ItemFieldSingleSelectValue{name optionId field{... on ProjectV2SingleSelectField{id name}}}}pageInfo{hasNextPage}}}pageInfo{hasNextPage endCursor}}}}}}"#;
    /// Files one issue under another as a sub-issue, which is what project membership is.
    pub const ADD_SUB_ISSUE: &str =
        r#"mutation($input:AddSubIssueInput!){addSubIssue(input:$input){issue{id} subIssue{id}}}"#;
    /// Takes one issue back out of its parent.
    pub const REMOVE_SUB_ISSUE: &str = r#"mutation($input:RemoveSubIssueInput!){removeSubIssue(input:$input){issue{id} subIssue{id}}}"#;
    /// Adds GitHub's native issue blocked-by relationship.
    pub const ADD_BLOCKED_BY: &str = r#"mutation($input:AddBlockedByInput!){addBlockedBy(input:$input){issue{id} blockingIssue{id}}}"#;
    /// Removes one native issue blocked-by relationship.
    pub const REMOVE_BLOCKED_BY: &str = r#"mutation($input:RemoveBlockedByInput!){removeBlockedBy(input:$input){issue{id} blockingIssue{id}}}"#;
    /// Deletes one issue, which takes its board item with it.
    ///
    /// The engine sends this in one situation only: undoing a copy that could not finish,
    /// over the items that same copy created. Deleting the issue removes the board item
    /// too, so there is no second `deleteProjectV2Item` to keep in step with it.
    pub const DELETE_ISSUE: &str =
        r#"mutation($input:DeleteIssueInput!){deleteIssue(input:$input){repository{id}}}"#;

    /// Everything this source reads about one issue comment, wherever it reaches one.
    ///
    /// A macro for the reason [`board_issue!`] is one: a comment listed, a comment just added
    /// and a comment just edited are handed to one mapper, so they are selected by one
    /// spelling. `author` is `Actor`, which GitHub answers `null` for an account that no
    /// longer exists, and `login` is the one member every kind of actor carries.
    macro_rules! issue_comment {
        () => {
            "id author{login} createdAt updatedAt body url"
        };
    }

    /// One task's comments: a page of its issue's own `comments` connection.
    ///
    /// **No `orderBy`, and that is what makes the page oldest first.** GitHub's only
    /// `IssueCommentOrder` field is `UPDATED_AT`, which would move a comment to the end of the
    /// list every time somebody edited it; left unordered the connection answers in the order
    /// the comments were written, which is the order GitHub documents for the same collection
    /// over REST — ascending id. Nothing multiplies through it, so `$first` is the whole of its
    /// node count and the caller's own page size is pushed straight down.
    pub const ISSUE_COMMENTS: &str = concat!(
        r#"query($id:ID!,$first:Int!,$after:String){node(id:$id){__typename ... on Issue{comments(first:$first,after:$after){nodes{"#,
        issue_comment!(),
        r#"}pageInfo{hasNextPage endCursor}}}}}"#
    );
    /// Which issue one comment is on, read before that comment is edited or removed.
    ///
    /// GitHub's comment mutations take the comment's id and nothing else, so without this a
    /// comment id given against the wrong task would change a comment on another issue.
    pub const COMMENT_ISSUE: &str =
        r#"query($id:ID!){node(id:$id){__typename ... on IssueComment{id issue{id}}}}"#;
    /// Adds one comment to an issue, signed as the account the token belongs to.
    pub const ADD_COMMENT: &str = concat!(
        r#"mutation($input:AddCommentInput!){addComment(input:$input){subject{id} commentEdge{node{"#,
        issue_comment!(),
        r#"}}}}"#
    );
    /// Replaces the body of one issue comment.
    pub const UPDATE_COMMENT: &str = concat!(
        r#"mutation($input:UpdateIssueCommentInput!){updateIssueComment(input:$input){issueComment{"#,
        issue_comment!(),
        r#"}}}"#
    );
    /// Removes one issue comment. Its payload carries nothing about the comment it removed.
    pub const DELETE_COMMENT: &str = r#"mutation($input:DeleteIssueCommentInput!){deleteIssueComment(input:$input){clientMutationId}}"#;

    /// Every document above, with what this source is doing when it sends one.
    ///
    /// One list rather than a `match` beside the constants: a rate-limit diagnostic has to
    /// name the call that was refused, and a `match` with a catch-all arm would answer a
    /// document added later with "talking to GitHub" and never say so.
    ///
    /// `documents_are_all_inventoried` reads this file back and fails naming any `pub
    /// const` here that this list omits, so the two cannot part — which is the same guard
    /// `CATEGORIES` carries, in the one shape available to a set of `&str` constants.
    pub const DOCUMENTS: [(&str, &str); 26] = [
        (SEARCH_ISSUES, "searching this board's issues"),
        (ISSUE, "reading one issue"),
        (
            ISSUE_BOARD_ITEMS,
            "reading one issue's board memberships past the page it came with",
        ),
        (SUB_ISSUES, "reading a project's tasks"),
        (BOARD, "reading the board"),
        (BOARD_FIELDS, "reading the board's fields"),
        (DRAFT, "reading one draft"),
        (REPOSITORY, "reading the destination repository"),
        (ISSUE_DEPENDENCIES, "reading an issue's dependencies"),
        (CREATE_ISSUE, "creating an issue"),
        (ADD_TO_BOARD, "adding an issue to the board"),
        (UPDATE_ISSUE, "updating an issue"),
        (UPDATE_DRAFT, "updating a draft item"),
        (UPDATE_FIELD, "writing a board field"),
        (
            STATUS_OPTIONS_SNAPSHOT,
            "snapshotting board Status options and assignments",
        ),
        (
            STATUS_OPTIONS_UPDATE,
            "safely replacing the board Status option list",
        ),
        (ADD_SUB_ISSUE, "filing an issue under its project"),
        (REMOVE_SUB_ISSUE, "taking an issue out of its project"),
        (ADD_BLOCKED_BY, "recording a dependency"),
        (REMOVE_BLOCKED_BY, "removing a dependency"),
        (DELETE_ISSUE, "deleting an issue"),
        (ISSUE_COMMENTS, "reading a task's comments"),
        (COMMENT_ISSUE, "reading which issue a comment is on"),
        (ADD_COMMENT, "adding a comment"),
        (UPDATE_COMMENT, "editing a comment"),
        (DELETE_COMMENT, "deleting a comment"),
    ];
}

/// Which of GitHub's two rate limiters refused a request.
///
/// Waiting is the whole answer to the primary budget, and polling is what *extends* the
/// secondary one — so an operator told the wrong one takes the wrong next step, which is
/// the whole reason this is carried rather than collapsed into "rate limited".
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Limiter {
    /// The hourly API budget, which `gh api rate_limit` reports and a wait answers.
    Primary,
    /// The burst limiter over content-generating requests, which nothing reports.
    Secondary,
}

/// The wordings GitHub answers a secondary rate limit with.
///
/// It sends them under a forbidden status, under a too-many-requests status, and inside
/// the `errors` of a *successful* response, which is why the text is what this matches on
/// rather than the status. `abuse detection` is the wording GitHub used before the
/// limiter was renamed and still returns from some endpoints; `submitted too quickly` is
/// what a burst of content creation is refused with.
///
/// This is GitHub's vocabulary rather than this source's, so it is pinned rather than
/// remembered: `tests/fixtures/rate-limits.json` records where each wording was read and
/// when, and the drift gate reconciles the two lists both ways. Public for that gate
/// alone — a caller has no use for it, and matching on a refusal is this source's job.
pub const SECONDARY_WORDINGS: [&str; 5] = [
    "secondary rate limit",
    "temporarily blocked from content creation",
    "abuse detection",
    "submitted too quickly",
    "exceeded a secondary",
];

/// The wordings GitHub answers an exhausted primary budget with.
///
/// `rate_limited` is the `type` its GraphQL error carries, which is read as a field rather
/// than looked for in the response text. Pinned and gated exactly as
/// [`SECONDARY_WORDINGS`] is, and public for the same one reason.
pub const PRIMARY_WORDINGS: [&str; 3] = [
    "api rate limit exceeded",
    "rate limit exceeded",
    "rate_limited",
];

/// What a response *says about itself*, which is the only place a refusal can be read.
///
/// Deliberately not the whole response body. A board is a place people write about their
/// own work, and a task on it titled "the secondary rate limit" would, matched across the
/// raw text, turn a perfectly good answer into a refusal this source then waited out and
/// reported. So the item data is never read: what is read is GitHub's own REST-style
/// `message` envelope, which is what a forbidden status carries, and the `message` and
/// `type` of each GraphQL error, which is where a *successful* response says it.
///
/// A body that is not JSON at all has nothing structured to read, so only a failing
/// response's own text is taken — a successful response that is not JSON is malformed
/// rather than refused, and [`GitHubProjectsSource::answer`] says so.
fn refusal_wording(status: StatusCode, body: &str) -> String {
    let Ok(parsed) = serde_json::from_str::<Value>(body) else {
        return if status.is_success() {
            String::new()
        } else {
            body.to_owned()
        };
    };
    let mut said: Vec<&str> = parsed
        .get("message")
        .and_then(Value::as_str)
        .into_iter()
        .collect();
    if let Some(errors) = parsed.get("errors").and_then(Value::as_array) {
        for error in errors {
            said.extend(
                ["message", "type"]
                    .into_iter()
                    .filter_map(|key| error.get(key).and_then(Value::as_str)),
            );
        }
    }
    said.join("; ")
}

impl Limiter {
    /// Which limiter refused this response, or `None` when none of them did.
    ///
    /// The wording is read first and the status only decides what carries none of it,
    /// because GitHub answers a secondary limit with a forbidden status far more often
    /// than with too-many-requests — while a forbidden status saying nothing about a limit
    /// really is a credential this token lacks.
    ///
    /// A response is a refusal because of its status or its own wording. A spent budget
    /// only ever explains one; it never turns an answer into a refusal.
    fn classify(status: StatusCode, budget_exhausted: bool, body: &str) -> Option<Self> {
        let normalized = refusal_wording(status, body).to_ascii_lowercase();
        if SECONDARY_WORDINGS
            .iter()
            .any(|wording| normalized.contains(wording))
        {
            return Some(Self::Secondary);
        }
        if status == StatusCode::TOO_MANY_REQUESTS {
            return Some(Self::Primary);
        }
        // An exhausted budget *explains* a response that failed; it does not make one that
        // succeeded into a failure. GitHub sets `x-ratelimit-remaining: 0` on the last
        // request the budget allowed as well as on the ones it then refuses, so reading
        // the header alone threw away a good answer — and, once refusals were retried,
        // replayed a request that had already taken effect.
        if !status.is_success() && budget_exhausted {
            return Some(Self::Primary);
        }
        // A successful response saying it: GitHub reports a GraphQL rate limit in the
        // `errors` of an HTTP 200, where nothing about the status says so at all.
        if status.is_success()
            && PRIMARY_WORDINGS
                .iter()
                .any(|wording| normalized.contains(wording))
        {
            return Some(Self::Primary);
        }
        None
    }

    /// What this limiter is called where an operator can look it up.
    const fn name(self) -> &'static str {
        match self {
            Self::Primary => "GitHub's primary API rate limit",
            Self::Secondary => "GitHub's secondary rate limit",
        }
    }

    /// What the endpoint an operator would go and check says about this limiter.
    const fn where_to_look(self) -> &'static str {
        match self {
            Self::Primary => {
                "That is the budget `gh api rate_limit` reports, so that endpoint says when it \
                 comes back."
            }
            Self::Secondary => {
                "That limiter is not the primary API budget: `gh api rate_limit` reports the \
                 primary budget and does not report this one, so budget showing there says \
                 nothing about this refusal, and every further attempt extends it."
            }
        }
    }

    /// The next step this limiter actually calls for.
    const fn what_to_do(self) -> &'static str {
        match self {
            Self::Primary => {
                "wait for the reset `gh api rate_limit` reports, then run the command again."
            }
            Self::Secondary => {
                "leave this board alone for a few minutes, then run the command again — or \
                 raise pacing.min_mutation_interval_ms on this source so it writes more slowly."
            }
        }
    }
}

/// One rate-limit refusal, and the wait GitHub asked for if it asked for one.
#[derive(Debug, Clone, Copy)]
struct Limited {
    limiter: Limiter,
    hint: Option<u64>,
}

impl Limited {
    /// What the caller is told once this source has waited as long as it may.
    ///
    /// Both limiters report as [`SourceError::RateLimited`], because that is what
    /// happened: the kind a caller matches on says a rate limit refused this, and nothing
    /// about *which* limiter it was makes it a different kind of failure. What differs is
    /// the operator's next step, and that is what the message carries — a secondary
    /// refusal read as a primary one sends an operator to `gh api rate_limit`, where the
    /// budget looks fine, and then back to retry the very burst that was refused.
    fn exhausted(
        self,
        doing: &str,
        waits: u32,
        waited: Duration,
        needed: Duration,
        budget: Duration,
    ) -> SourceError {
        SourceError::RateLimited {
            retry_after_seconds: self.hint,
            message: Some(format!(
                "{} refused this source while {doing}; it waited {} out over {} and was refused \
                 again, and the next wait of {} would take it past the {} one call may spend \
                 waiting. {} next: {}",
                self.limiter.name(),
                plural(waits, "refusal"),
                seconds(waited),
                seconds(needed),
                seconds(budget),
                self.limiter.where_to_look(),
                self.limiter.what_to_do(),
            )),
        }
    }
}

/// One HTTP attempt's result, with what its response said about the rate limit.
///
/// The two travel together so the record and the outcome are written from the same place:
/// what a response said about the budget is only readable while that response is in hand,
/// and what the attempt *meant* is only decidable once its body has been read.
struct Attempted {
    result: Result<Value, Attempt>,
    limits: accounting::RateLimit,
    /// GitHub's own reported cost for this call, for a document that asked for it.
    reported_cost: Option<u64>,
}

/// One attempt's outcome: an error to report, or a rate limit to wait out.
enum Attempt {
    Failed(SourceError),
    Limited(Limited),
}

fn plural(count: u32, thing: &str) -> String {
    if count == 1 {
        format!("{count} {thing}")
    } else {
        format!("{count} {thing}s")
    }
}

fn seconds(duration: Duration) -> String {
    format!("{:.1}s", duration.as_secs_f64())
}

/// A header GitHub spells as a whole number of seconds, or `None` when this one is not.
///
/// A value that is present and unreadable is deliberately *not* an error. `retry-after` is
/// allowed by HTTP to be a date rather than a count, an intermediary can rewrite either
/// header, and neither is what makes a response a refusal — so the whole cost of one this
/// cannot read is that the refusal carries no hint and the backing-off schedule answers it
/// instead. Refusing the response over the header would turn a readable refusal into an
/// unreadable one, and refusing to *wait* would be the one wrong direction to fail in.
fn whole_seconds(value: Option<&reqwest::header::HeaderValue>) -> Option<u64> {
    value
        .and_then(|value| value.to_str().ok())
        .and_then(|value| value.trim().parse::<u64>().ok())
}

/// Every mutation this source sends creates content — an issue, a board item, a field of
/// one, a sub-issue link, a dependency, a comment — or edits or removes content of that
/// kind, and no query in [`graphql::DOCUMENTS`] does, so what the secondary limiter counts
/// and what the keyword says are the same set. That is what makes the keyword a sound test
/// rather than a convenient one: pacing an edit or a removal the limiter might not have
/// counted costs a wait, and not pacing one it did count costs the next fifty minutes.
fn is_mutation(query: &str) -> bool {
    query.trim_start().starts_with("mutation")
}

/// What this source was doing, for a diagnostic that has to say so.
///
/// Read out of [`graphql::DOCUMENTS`], which is the inventory rather than a copy of it, so
/// a document added without a description is caught by that list's own gate instead of
/// falling through to the vague arm below.
fn operation_description(query: &str) -> &'static str {
    graphql::DOCUMENTS
        .iter()
        .find(|(document, _)| *document == query)
        .map_or("talking to GitHub", |(_, doing)| *doing)
}

/// GitHub's published ceiling on content-generating requests, per minute.
///
/// Pinned in `tests/fixtures/rate-limits.json` and gated against it, because it is
/// GitHub's number rather than this source's: [`MIN_MUTATION_INTERVAL_MS`] is *derived*
/// from it, so a pacing value checked only against itself cannot go stale here.
pub const CONTENT_CREATION_PER_MINUTE: u64 = 80;
/// The same ceiling as GitHub publishes it per hour, which this source does **not** pace
/// at. See [`MIN_MUTATION_INTERVAL_MS`] for why the per-minute bound is the one that
/// governs; it is pinned beside its sibling so the gate would notice either one moving.
pub const CONTENT_CREATION_PER_HOUR: u64 = 500;
/// Shortest interval between two content-creating mutations, in milliseconds.
///
/// GitHub documents two secondary limits on content-generating requests:
/// [`CONTENT_CREATION_PER_MINUTE`] and [`CONTENT_CREATION_PER_HOUR`]. 60000/80 is 750, so
/// a mutation every 750 ms is the fastest rate that cannot exceed the per-minute bound,
/// and that is the bound a copy actually trips: a copy of one plan-sized project is a
/// burst of a few dozen mutations inside a few seconds. The hourly bound works out at one
/// every 7.2 seconds sustained, which no single copy reaches and which, used as the
/// spacing here, would turn an ordinary copy into an hour of waiting — so it is
/// deliberately *not* what this paces at. An installation that wants the hourly bound
/// honoured for a long sequence of copies says so through
/// `pacing.min_mutation_interval_ms`.
pub const MIN_MUTATION_INTERVAL_MS: u64 = 60_000 / CONTENT_CREATION_PER_MINUTE;
/// First wait when a rate-limit refusal carries no hint; each further wait doubles it.
///
/// A doubling schedule from one second reaches a minute in six waits, which is GitHub's
/// own advice for a secondary limit — wait, and wait longer each time — without spending
/// the first minute of a transient refusal doing nothing.
pub const RETRY_BACKOFF_MS: u64 = 1_000;
/// Total time one call may spend waiting out rate limits before it reports a failure.
///
/// Two minutes is long enough to ride out the refusals a paced copy still collects and
/// short enough that a command an operator is watching returns. The bound is what makes
/// the wait a wait rather than a hang: a call refused past it ends in a diagnostic naming
/// the limiter, not in a process nobody can tell from a wedged one.
pub const RETRY_BUDGET_MS: u64 = 120_000;

fn default_token_env() -> String {
    "GH_PROJECTS_TOKEN".to_owned()
}
fn default_endpoint() -> String {
    "https://api.github.com/graphql".to_owned()
}

/// Where one status category lands on this board.
///
/// `null` — an absent value — disables the category for this instance, and using a
/// disabled status is a refusal naming the status and the instance.
#[derive(Debug, Clone, Deserialize, schemars::JsonSchema)]
#[serde(untagged)]
pub enum StatusTargetConfig {
    /// The name of a `Status` single-select option already on the board.
    Column(ColumnName),
}

/// The name of a `Status` single-select option on the board.
///
/// Validated on the way in rather than checked later, so a blank option name — which
/// nothing on a board can be — is a state this type cannot hold.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize, schemars::JsonSchema)]
#[serde(try_from = "String")]
#[schemars(extend("minLength" = 1))]
pub struct ColumnName(String);

impl ColumnName {
    /// The option name, as the board spells it.
    fn as_str(&self) -> &str {
        &self.0
    }
}

impl TryFrom<String> for ColumnName {
    type Error = String;

    fn try_from(name: String) -> Result<Self, Self::Error> {
        if name.trim().is_empty() {
            return Err("a status_mapping option name cannot be blank".to_owned());
        }
        Ok(Self(name))
    }
}

/// The two closed states this product can mean.
///
/// GitHub's `IssueClosedStateReason` also spells `DUPLICATE`, which is neither finished
/// work nor abandoned work, so nothing here ever writes it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, schemars::JsonSchema)]
#[serde(rename_all = "kebab-case")]
pub enum ClosedState {
    /// `COMPLETED` — precisely done.
    Completed,
    /// `NOT_PLANNED` — precisely cancelled.
    NotPlanned,
}

impl ClosedState {
    const fn reason(self) -> &'static str {
        match self {
            Self::Completed => "COMPLETED",
            Self::NotPlanned => "NOT_PLANNED",
        }
    }
}

/// Configuration for one GitHub Projects v2 board.
#[derive(Debug, Clone, Default, Deserialize, schemars::JsonSchema)]
#[serde(default, deny_unknown_fields)]
pub struct GitHubProjectsConfig {
    /// Login of the user or organization which owns the board.
    pub owner: String, // llmlint: ignore[invalid_states_unrepresentable] Schema DTO; `new` validates GitHub's owner grammar before private construction.
    /// The project number shown in the board's GitHub URL.
    pub project_number: u32, // llmlint: ignore[invalid_states_unrepresentable] Schema DTO; `new` bounds this to a positive GraphQL Int.
    // llmlint: ignore-block[contracts_have_one_source_or_a_drift_gate] This doc is the field's schema description, which is what a person configuring the source reads, so it has to say when the field decides an issue's repository and when the item's own field does; the rule's one executable source is `GitHubProjectsSource::creation_target`, and `tests/plugin.rs` drives each case named here against the loopback board.
    /// `owner/name` of the repository this source creates an issue in when the item's own
    /// `repositories` field does not decide it.
    ///
    /// An item naming exactly one repository is created there; a task or a document naming
    /// none or several is created in its parent project's repository; and a project, or a
    /// task or document with no parent, naming none or several is created here. A board
    /// has no repository of its own and `createIssue` requires one, so a write without
    /// this is refused naming the field. Reads never need it.
    pub repository: Option<String>, // llmlint: ignore[invalid_states_unrepresentable] Schema DTO; `new` validates the `owner/name` grammar before private construction.
    // llmlint: ignore-end[contracts_have_one_source_or_a_drift_gate]
    /// Environment variable containing a fine-grained token with Projects and Issues
    /// read/write plus Pull requests read-only access for every repository represented on
    /// the board.
    #[serde(default = "default_token_env")]
    pub token_env: String, // llmlint: ignore[invalid_states_unrepresentable] Schema DTO; `new` validates the environment-variable grammar.
    /// GraphQL endpoint. GitHub Enterprise installations may override it.
    #[serde(default = "default_endpoint")]
    pub endpoint: String, // llmlint: ignore[invalid_states_unrepresentable] Schema DTO; `new` converts it to the private validated `Url`.
    /// Per-instance mapping from a status category to where it lands on this board.
    ///
    /// A category this does not mention keeps its shipped default: `backlog` to
    /// "Backlog", `todo` to "Todo", `queued` to "Queued", `in-progress` to "In Progress",
    /// `done` to "Done" plus closed as completed, `cancelled` to "Cancelled" plus closed
    /// as not planned, and `draft` and `unknown` disabled. `unknown` may name one existing
    /// board option; every unknown word then lands on that option and reads back as
    /// `unknown` under its name. Unlike `local-md`, this source cannot keep each unknown
    /// word because it never creates board options.
    #[serde(default)]
    pub status_mapping: BTreeMap<String, Option<StatusTargetConfig>>, // llmlint: ignore[invalid_states_unrepresentable] Schema DTO; `new` parses each key into a `StatusCategory` and reports an unknown one against this instance.
    /// How fast this source writes, and how long it waits out a rate-limit refusal.
    ///
    /// Every field keeps its shipped default when it is absent, and the defaults are
    /// GitHub's own published limits rather than taste. See [`Pacing`].
    #[serde(default)]
    pub pacing: PacingConfig,
}

/// How fast this source writes, and how long it waits out a rate-limit refusal.
///
/// Configurable because a GitHub Enterprise installation sets its own limits and an
/// operator who has already been refused may want to go slower still — not because the
/// defaults are guesses.
#[derive(Debug, Clone, Default, Deserialize, schemars::JsonSchema)]
#[serde(default, deny_unknown_fields)]
pub struct PacingConfig {
    /// Shortest interval between two content-creating mutations, in milliseconds.
    ///
    /// Zero sends them as fast as they are asked for, which is what a fixture server on
    /// loopback wants and what no board on github.com does. At most [`MAX_PACING_MS`].
    pub min_mutation_interval_ms: Option<u64>, // llmlint: ignore[invalid_states_unrepresentable] Schema DTO; `Pacing::resolve` bounds it to `MAX_PACING_MS` before the private validated `Pacing` is built.
    /// First wait when a rate-limit refusal carries no hint, in milliseconds. Each
    /// further wait of the same call doubles it. At most [`MAX_PACING_MS`], and never
    /// zero while there is a budget to spend, because a schedule of zero-length waits
    /// consumes none of it and so never ends.
    pub retry_backoff_ms: Option<u64>, // llmlint: ignore[invalid_states_unrepresentable] Schema DTO; `Pacing::resolve` refuses a non-progressing zero and bounds the rest before the private validated `Pacing` is built.
    /// Total time one call may spend waiting out rate limits, in milliseconds.
    ///
    /// Zero reports the refusal rather than waiting at all. At most [`MAX_PACING_MS`]:
    /// the bound is what makes this a wait rather than a hang.
    pub retry_budget_ms: Option<u64>, // llmlint: ignore[invalid_states_unrepresentable] Schema DTO; `Pacing::resolve` bounds it to `MAX_PACING_MS` before the private validated `Pacing` is built.
}

/// The largest any pacing setting may be, in milliseconds.
///
/// One hour. GitHub's own harshest published bound on content-generating requests works
/// out at one every 7.2 seconds, so an hour is already three orders of magnitude past
/// anything a real limit asks for, and past it the settings stop describing pacing at all:
/// a wait budget beyond it is the unbounded wait this whole mechanism exists to replace,
/// and an interval beyond it is a command that never sends its second mutation. It also
/// keeps the clock arithmetic in [`GitHubProjectsSource::reserve_mutation_slot`] inside
/// what an `Instant` can hold on every platform.
pub const MAX_PACING_MS: u64 = 3_600_000;

/// [`PacingConfig`] with every default resolved and every value checked, which is what the
/// source holds.
#[derive(Debug, Clone, Copy)]
struct Pacing {
    min_mutation_interval: Duration,
    retry_backoff: Duration,
    retry_budget: Duration,
}

impl Pacing {
    /// Resolve one instance's pacing, refusing a configuration that would not pace at all.
    fn resolve(config: PacingConfig, instance: &SourceName) -> Result<Self, SourceError> {
        let bounded = |value: Option<u64>, default: u64, field: &str| match value {
            Some(value) if value > MAX_PACING_MS => Err(SourceError::Config {
                message: format!(
                    "pacing.{field} of source {instance} is {value} ms, and the most any pacing \
                     setting may be is {MAX_PACING_MS} ms — an hour, which is already far past \
                     GitHub's own harshest published limit"
                ),
            }),
            Some(value) => Ok(Duration::from_millis(value)),
            None => Ok(Duration::from_millis(default)),
        };
        let retry_backoff = bounded(
            config.retry_backoff_ms,
            RETRY_BACKOFF_MS,
            "retry_backoff_ms",
        )?;
        let retry_budget = bounded(config.retry_budget_ms, RETRY_BUDGET_MS, "retry_budget_ms")?;
        if retry_backoff.is_zero() && !retry_budget.is_zero() {
            return Err(SourceError::Config {
                message: format!(
                    "pacing.retry_backoff_ms of source {instance} is 0 while \
                     pacing.retry_budget_ms is {} ms; a schedule of zero-length waits spends \
                     none of that budget, so it would retry a refusal forever. Set a backoff of \
                     at least 1 ms, or set retry_budget_ms to 0 to report a refusal without \
                     waiting at all",
                    retry_budget.as_millis()
                ),
            });
        }
        Ok(Self {
            min_mutation_interval: bounded(
                config.min_mutation_interval_ms,
                MIN_MUTATION_INTERVAL_MS,
                "min_mutation_interval_ms",
            )?,
            retry_backoff,
            retry_budget,
        })
    }
}

/// Factory for [`GitHubProjectsSource`].
#[derive(Debug, Clone, Copy, Default)]
pub struct Plugin;

impl SourcePlugin for Plugin {
    fn kind(&self) -> &'static str {
        KIND
    }
    fn config_schema(&self) -> Schema {
        schema_for!(GitHubProjectsConfig)
    }
    fn build(
        &self,
        name: &SourceName,
        config: &Value,
        secrets: &dyn SecretResolver,
    ) -> Result<Box<dyn TaskSource>, SourceError> {
        self.build_recording_into(name, config, secrets, Arc::new(Accounting::new()))
    }
}

impl Plugin {
    /// Build a source recording every request it sends into an accounting the caller holds.
    ///
    /// [`SourcePlugin::build`] is this with an accounting of its own, which is what the
    /// registry gets. This is for a caller that is also calling GitHub itself and wants one
    /// session total rather than two — see [`accounting`] and
    /// [`GitHubProjectsSource::recording_into`].
    ///
    /// # Errors
    ///
    /// Exactly [`SourcePlugin::build`]'s, with the same source name in front of each:
    /// [`SourceError::Config`] for configuration this plugin cannot use and
    /// [`SourceError::Auth`] for a credential it cannot find.
    pub fn build_recording_into(
        &self,
        name: &SourceName,
        config: &Value,
        secrets: &dyn SecretResolver,
        ledger: Arc<Accounting>,
    ) -> Result<Box<dyn TaskSource>, SourceError> {
        let config: GitHubProjectsConfig =
            serde_json::from_value(config.clone()).map_err(|e| SourceError::Config {
                message: format!("source {name}: {e}"),
            })?;
        let source = GitHubProjectsSource::recording_into(name, config, secrets, ledger).map_err(
            |error| match error {
                SourceError::Config { message } => SourceError::Config {
                    message: format!("source {name}: {message}"),
                },
                SourceError::Auth { message } => SourceError::Auth {
                    message: format!("source {name}: {message}"),
                },
                other => other,
            },
        )?;
        Ok(Box::new(source))
    }
}

/// Where a status category lands on this board, once configuration is resolved.
#[derive(Debug, Clone, PartialEq, Eq)]
enum StatusTarget {
    /// Not usable against this instance.
    Disabled,
    /// The board's `Status` option of this name.
    Column(ColumnName),
    /// A closed issue, with both its board option and the reason that says which closed it means.
    // llmlint: ignore[invalid_states_unrepresentable] The reason is fixed by the category — `done` closes as completed, `cancelled` as not planned — and this private enum is built in one place, `StatusMapping::new`, which pairs each from the category's own slot. Carrying the reason on the target is what lets every write site that holds only a target derive its `stateInput` from that one resolved model rather than re-deriving it from a category and risking a disagreement with the mapping.
    Terminal(ColumnName, ClosedState),
}

/// Every status category, in the order the vocabulary declares them.
///
/// This list mirrors `StatusCategory`, so it carries its own drift gate rather than a
/// reviewer's attention: [`category_position`] is a wildcard-free match, so a variant
/// added to the shared vocabulary fails to compile until it is named there, and this
/// crate's suite reconciles this list against that enum's own derived schema, which is
/// generated from the variants rather than written beside them. The schema is what
/// catches a list left one short — a list checking only the positions it already holds
/// would pass while every mapping indexed by the new position panicked.
pub const CATEGORIES: [StatusCategory; 8] = [
    StatusCategory::Draft,
    StatusCategory::Backlog,
    StatusCategory::Todo,
    StatusCategory::Queued,
    StatusCategory::InProgress,
    StatusCategory::Done,
    StatusCategory::Cancelled,
    StatusCategory::Unknown,
];

/// Where one category sits in [`CATEGORIES`]; see that list for what this pins.
#[must_use]
pub const fn category_position(category: StatusCategory) -> usize {
    match category {
        StatusCategory::Draft => 0,
        StatusCategory::Backlog => 1,
        StatusCategory::Todo => 2,
        StatusCategory::Queued => 3,
        StatusCategory::InProgress => 4,
        StatusCategory::Done => 5,
        StatusCategory::Cancelled => 6,
        StatusCategory::Unknown => 7,
    }
}

/// The spelling a status category is configured and reported under.
fn category_name(category: StatusCategory) -> &'static str {
    match category {
        StatusCategory::Draft => "draft",
        StatusCategory::Backlog => "backlog",
        StatusCategory::Todo => "todo",
        StatusCategory::Queued => "queued",
        StatusCategory::InProgress => "in-progress",
        StatusCategory::Done => "done",
        StatusCategory::Cancelled => "cancelled",
        StatusCategory::Unknown => "unknown",
    }
}

/// A shipped default's option name.
///
/// The literals below are this file's own and non-blank, and they are validated by the
/// one constructor a configured name goes through rather than beside it.
fn shipped_column(name: &'static str) -> ColumnName {
    ColumnName::try_from(name.to_owned()).expect("a shipped default names a board option")
}

/// The shipped default for one category, before this instance's configuration.
fn shipped_default(category: StatusCategory) -> StatusTarget {
    match category {
        StatusCategory::Backlog => StatusTarget::Column(shipped_column("Backlog")),
        StatusCategory::Todo => StatusTarget::Column(shipped_column("Todo")),
        StatusCategory::Queued => StatusTarget::Column(shipped_column("Queued")),
        StatusCategory::InProgress => StatusTarget::Column(shipped_column("In Progress")),
        StatusCategory::Done => {
            StatusTarget::Terminal(shipped_column("Done"), ClosedState::Completed)
        }
        StatusCategory::Cancelled => {
            StatusTarget::Terminal(shipped_column("Cancelled"), ClosedState::NotPlanned)
        }
        StatusCategory::Draft | StatusCategory::Unknown => StatusTarget::Disabled,
    }
}

/// This instance's complete category-to-target mapping, read in both directions.
///
/// One target per category, held at that category's own [`category_position`], so a
/// category missing from the mapping, named twice in it, or filed out of order is a
/// state this type cannot hold rather than one [`Self::target`] has to defend against.
#[derive(Debug, Clone)]
struct StatusMapping {
    targets: [StatusTarget; CATEGORIES.len()],
}

impl StatusMapping {
    fn resolve(
        configured: BTreeMap<String, Option<StatusTargetConfig>>,
        instance: &SourceName,
    ) -> Result<Self, SourceError> {
        let mut overrides: BTreeMap<&'static str, Option<StatusTargetConfig>> = BTreeMap::new();
        for (key, value) in configured {
            let category = CATEGORIES
                .iter()
                .find(|category| category_name(**category) == key)
                .ok_or_else(|| SourceError::Config {
                    message: format!(
                        "status_mapping names {key:?}, which is not a status category of source \
                         {instance}; the categories are {}",
                        CATEGORIES
                            .iter()
                            .map(|category| category_name(*category))
                            .collect::<Vec<_>>()
                            .join(", ")
                    ),
                })?;
            overrides.insert(category_name(*category), value);
        }
        // `CATEGORIES[position] == category` for every category — the crate's suite
        // asserts it — so mapping the list in order fills each category's own slot.
        let targets = CATEGORIES.map(|category| match overrides.remove(category_name(category)) {
            None => shipped_default(category),
            Some(None) => StatusTarget::Disabled,
            Some(Some(StatusTargetConfig::Column(option))) => match category {
                StatusCategory::Done => StatusTarget::Terminal(option, ClosedState::Completed),
                StatusCategory::Cancelled => {
                    StatusTarget::Terminal(option, ClosedState::NotPlanned)
                }
                _ => StatusTarget::Column(option),
            },
        });
        let mapping = Self { targets };
        for (index, category) in CATEGORIES.into_iter().enumerate() {
            let option = match mapping.target(category) {
                StatusTarget::Column(option) | StatusTarget::Terminal(option, _) => option,
                StatusTarget::Disabled => continue,
            };
            if let Some(other) = CATEGORIES[..index].iter().find(|earlier| {
                matches!(mapping.target(**earlier), StatusTarget::Column(name) | StatusTarget::Terminal(name, _)
                    if name.as_str().eq_ignore_ascii_case(option.as_str()))
            }) {
                return Err(SourceError::Config {
                    message: format!(
                        "status_mapping of source {instance} sends both {} and {} to the board \
                         option {:?}; one option cannot read back as two categories",
                        category_name(*other),
                        category_name(category),
                        option.as_str()
                    ),
                });
            }
        }
        Ok(mapping)
    }

    fn target(&self, category: StatusCategory) -> &StatusTarget {
        &self.targets[category_position(category)]
    }

    /// The category a board option name reports, or `None` when nothing maps to it.
    fn category_of(&self, option: &str) -> Option<StatusCategory> {
        CATEGORIES.into_iter().find(|category| {
            matches!(self.target(*category), StatusTarget::Column(name) | StatusTarget::Terminal(name, _)
                if name.as_str().eq_ignore_ascii_case(option))
        })
    }

    /// The status an item reports, from the three things a read of it says: its board
    /// `Status` option, whether its issue is closed, and the reason it was closed with.
    ///
    /// The closed state decides the category and the `Status` option decides the name, so
    /// a closed issue sitting in a "Shipped" column reports `done` named `Shipped`. A
    /// closed issue whose reason is `DUPLICATE` or `REOPENED` reports `Unknown`: a
    /// duplicate is not finished work, and calling it done is a lie the next copy would
    /// write back. `REOPENED`-while-closed is a state this source can never produce, so
    /// it is read permissively rather than refused — reads are faithful, and refusals
    /// belong on writes.
    ///
    /// One function of those three rather than of a response, so a narrow status write can
    /// answer what a re-read would report by applying it to the state it has just written.
    fn status(&self, option: Option<&str>, closed: bool, reason: Option<&str>) -> Status {
        if closed {
            let category = match reason {
                None | Some("COMPLETED") => StatusCategory::Done,
                Some("NOT_PLANNED") => StatusCategory::Cancelled,
                Some(_) => StatusCategory::Unknown,
            };
            let fallback = match category {
                StatusCategory::Done => "Done",
                StatusCategory::Cancelled => "Cancelled",
                _ => "Closed",
            };
            return Status {
                category,
                name: option.unwrap_or(fallback).to_owned(),
            };
        }
        let name = option.unwrap_or("Open").to_owned();
        Status {
            category: self.category_of(&name).unwrap_or(StatusCategory::Unknown),
            name,
        }
    }
}

// llmlint: ignore-block[comments_earn_their_place, contracts_have_one_source_or_a_drift_gate] Every `createIssue` names one of these, and which one is the rule — a reader who reaches the type from `create_and_file_issue` gets the rule in one sentence here without the method's refusals, which stay on `creation_target`, the rule's one executable source; `tests/plugin.rs` drives every arm of it against the loopback board.
/// One repository this source can create an issue in, as `owner/name`.
///
/// Every `createIssue` this source sends names one of these: the item's own single
/// `repositories` entry, else its parent project issue's repository, else the configured
/// [`GitHubProjectsConfig::repository`]. [`GitHubProjectsSource::creation_target`] makes
/// that choice and says what it refuses before `createIssue`.
// llmlint: ignore-end[comments_earn_their_place, contracts_have_one_source_or_a_drift_gate]
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
struct RepositoryTarget {
    owner: String, // llmlint: ignore[invalid_states_unrepresentable] Private, constructed only after `owner/name` validation in `new`.
    name: String, // llmlint: ignore[invalid_states_unrepresentable] Private, constructed only after `owner/name` validation in `new`.
}

impl RepositoryTarget {
    fn parse(value: &str) -> Result<Self, SourceError> {
        let (owner, name) = value.split_once('/').ok_or_else(|| SourceError::Config {
            message: format!(
                "repository must be spelled owner/name; {value:?} names no repository"
            ),
        })?;
        if !valid_github_owner(owner) || !valid_github_repository_name(name) {
            return Err(SourceError::Config {
                message: format!(
                    "repository must be spelled owner/name with a GitHub login and one \
                     repository name; {value:?} is not"
                ),
            });
        }
        Ok(Self {
            owner: owner.to_owned(),
            name: name.to_owned(),
        })
    }

    /// The one host whose repositories this source creates issues in, spelled once: it is
    /// what [`Self::origin`] renders and what [`Self::from_origin`] accepts.
    const HOST: &str = "github.com";

    fn origin(&self) -> String {
        format!("{}/{}/{}", Self::HOST, self.owner, self.name)
    }

    /// The repository a normalized origin names, or why it is none this source can create
    /// an issue in: another host, or more or fewer than `owner/name` under this one.
    fn from_origin(origin: &Repository) -> Result<Self, String> {
        let not_here = || {
            format!(
                "{} is not a {}/owner/name repository",
                origin.as_str(),
                Self::HOST
            )
        };
        let (host, rest) = origin.as_str().split_once('/').ok_or_else(not_here)?;
        if host != Self::HOST {
            return Err(not_here());
        }
        Self::parse(rest).map_err(|_| not_here())
    }

    fn slug(&self) -> String {
        format!("{}/{}", self.owner, self.name)
    }
}

/// A source which reads GitHub afresh for every operation.
pub struct GitHubProjectsSource {
    /// This source's configured name, used both to tell a far end naming this source
    /// from one naming a system it knows nothing about, and to name the instance a
    /// status refusal is about.
    name: SourceName,
    owner: String, // llmlint: ignore[invalid_states_unrepresentable] Private, constructed only by `new` after full GitHub-owner validation.
    project_number: u32, // llmlint: ignore[invalid_states_unrepresentable] Private, constructed only by `new` after GraphQL-Int validation.
    repository: Option<RepositoryTarget>,
    endpoint: Url,
    token: SecretString,
    credential_name: String, // llmlint: ignore[invalid_states_unrepresentable] Private diagnostic value constructed only after environment-name validation.
    statuses: StatusMapping,
    client: Client,
    /// Every item this source has created since it was built, in the order it created
    /// them.
    ///
    /// GitHub's `projectV2.items` is eventually consistent: an issue added to a board with
    /// `addProjectV2ItemById` is routinely absent from the very next read of that board, so
    /// a copy resolving a dependency on an item it had just created refused it as not
    /// found. A board read is completed from this — an item remembered here and absent from
    /// the read is added back, because the board really does hold it and only the read is
    /// behind.
    ///
    /// It is not a cache of a user's work: nothing is remembered that this process did not
    /// itself just write, it lives and dies with the process, and it is never consulted for
    /// an item this source did not create.
    created: Mutex<Vec<Resolved>>,
    /// How fast this source writes, and how long it waits out a refusal.
    pacing: Pacing,
    /// When the last content-creating mutation finished, or the moment the furthest-out
    /// reserved slot releases the next one, whichever is later — so the one after it can be
    /// spaced from that. See [`MIN_MUTATION_INTERVAL_MS`] for the interval and
    /// [`GitHubProjectsSource::finish_mutation`] for why completion rather than release is
    /// what it is measured from.
    last_mutation: Mutex<Option<Instant>>,
    /// The board as this process last read it, for the length of one command.
    ///
    /// A copy of a project used to re-read the whole board, paged, before writing each of
    /// its items, which is by far the largest part of a copy's request count and none of
    /// its work. Nothing else changes this board while a command runs — this source's own
    /// writes are the only writer — so one read answers them all.
    ///
    /// It is not a store of a user's work and it is not the cache the no-persistence
    /// invariant forbids: it lives and dies with the process exactly as `created` does,
    /// nothing is written down, and [`Self::board`] still completes it from `created`, so
    /// an item this command created and then depends on resolves whether or not GitHub's
    /// own eventually-consistent read has caught up. A write to an item already on the
    /// board updates the entry here too, so what this holds is the last read plus this
    /// process's own writes rather than a snapshot taken before them.
    board_cache: Mutex<Option<Board>>,
    /// Every issue this board's own search reported, for the length of one command.
    ///
    /// The second half of a board read, and cached for the same reason and on the same
    /// terms as the first: it lives and dies with the process, nothing is written down, and
    /// a write this process makes updates the entry here exactly as it updates the one in
    /// [`Self::board_cache`]. One read answers every question a command asks, so a command
    /// that lists this board's projects and its tasks pays for one search rather than two.
    search_cache: Mutex<Option<Vec<Resolved>>>,
    /// The board's own id and field definitions as this process last read them on their
    /// own, for the length of one command.
    ///
    /// What a write needs of the board and its item does not say, read once per command
    /// rather than once per item written, on the terms [`Self::board_cache`] is held on: it
    /// lives and dies with the process and nothing is written down. It holds no item and so
    /// can answer no question about one — see [`Self::board_fields`].
    fields_cache: Mutex<Option<BoardFields>>,
    /// Each destination repository's node id, resolved once per repository
    /// rather than per issue created.
    ///
    /// A repository's node id does not change, and re-reading it for every issue of a copy
    /// spent one request per item on an answer this source already had. It is a map rather
    /// than one entry because a copy files each item in the repository its own
    /// `repositories` field names, so a plan across five repositories asks GitHub five
    /// times and not once per item.
    repository_cache: Mutex<BTreeMap<RepositoryTarget, String>>,
    /// What every request this source sends is recorded into.
    ///
    /// Ordinary code path, not a mode: [`Self::send_once`] records into it at the one place
    /// a request leaves this crate, so nothing has to be switched on for a session to be
    /// counted. It is shared rather than owned so a caller accounting for a whole session —
    /// its own schema verification, board lookups, residue sweep and cleanup beside this
    /// source's reads and writes — adds up one accounting instead of two. See
    /// [`accounting`] for what a record carries and what a session's spend is and is not.
    ledger: Arc<Accounting>,
}

/// GitHub's closed single-select color vocabulary.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize, schemars::JsonSchema)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum StatusOptionColor {
    /// Gray.
    Gray,
    /// Blue.
    Blue,
    /// Green.
    Green,
    /// Yellow.
    Yellow,
    /// Purple.
    Purple,
    /// Red.
    Red,
    /// Orange.
    Orange,
    /// Pink.
    Pink,
}

/// Whether the guarded operation plans or applies additions.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StatusOptionsMode {
    /// Read without mutation.
    Plan,
    /// Apply and verify.
    Apply,
}

/// The explicit result of the requested operation.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, schemars::JsonSchema)]
#[serde(rename_all = "kebab-case")]
pub enum StatusOptionsOutcome {
    /// A read-only plan.
    Planned,
    /// Apply found nothing missing.
    Unchanged,
    /// Additions were applied and verified.
    Applied,
}

/// A GitHub single-select option's opaque GraphQL node identifier.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, schemars::JsonSchema)]
#[serde(transparent)]
pub struct StatusOptionId(#[schemars(length(min = 1))] String);

impl TryFrom<String> for StatusOptionId {
    type Error = String;

    fn try_from(id: String) -> Result<Self, Self::Error> {
        if id.trim().is_empty() {
            return Err("a GitHub Status option id cannot be blank".to_owned());
        }
        Ok(Self(id))
    }
}

/// One existing or proposed option in a guarded Status-field update.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, schemars::JsonSchema)]
pub struct StatusOption {
    /// GitHub's stable id.
    pub id: StatusOptionId,
    /// The visible option name.
    pub name: ColumnName,
    /// GitHub's single-select color token.
    pub color: StatusOptionColor,
    /// The option description, including an empty one.
    pub description: String,
}

/// One board item's Status assignment, retained as recovery data.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, schemars::JsonSchema)]
pub struct StatusAssignment {
    /// The project item id whose assignment this is.
    // llmlint: ignore[invalid_states_unrepresentable] This opaque GraphQL node ID is
    // carried verbatim as operator recovery data; introducing a semantic type would claim
    // validation rules GitHub does not publish and no operation here interprets.
    pub item_id: String,
    /// The selected option, absent when the item has no status.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub option: Option<AssignedStatusOption>,
}

/// The inseparable id and name of an assigned option.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, schemars::JsonSchema)]
pub struct AssignedStatusOption {
    /// GitHub's stable id.
    pub id: StatusOptionId,
    /// The visible name.
    pub name: ColumnName,
}

/// The plan and verified outcome of reconciling configured Status options.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, schemars::JsonSchema)]
pub struct StatusOptionsReport {
    /// The configured source name.
    pub source: SourceName,
    /// Configured option names absent before the operation.
    // llmlint: ignore[invalid_states_unrepresentable] Each value originates from a
    // `ColumnName` and has therefore already passed its nonblank validation; retaining the
    // serialized string here preserves the report's intentionally simple public contract.
    pub missing: Vec<String>,
    /// What the requested operation did.
    pub outcome: StatusOptionsOutcome,
    /// The complete option list observed before any mutation.
    pub existing: Vec<StatusOption>,
}

#[derive(Debug, Clone, PartialEq, Eq)]
struct StatusSnapshot {
    // llmlint: ignore[invalid_states_unrepresentable] This private opaque GraphQL ID is
    // passed back as the mutation's project identity; a newtype could enforce no stronger
    // invariant because GitHub publishes no grammar for it.
    board_id: String,
    // llmlint: ignore[invalid_states_unrepresentable] This private opaque GraphQL ID is
    // passed back as the mutation's field identity; a newtype could enforce no stronger
    // invariant because GitHub publishes no grammar for it.
    field_id: String,
    options: Vec<StatusOption>,
    assignments: Vec<StatusAssignment>,
}

impl GitHubProjectsSource {
    /// Report missing configured Status options and, when `apply` is true, add them with
    /// a whole-list mutation that preserves every existing id and verifies the result.
    ///
    /// # Errors
    ///
    /// Refuses a board without a single-select `Status` field. A post-write difference in
    /// any pre-existing option id or item assignment is refused with the complete pre-write
    /// assignment snapshot in the diagnostic for recovery.
    // llmlint: ignore[changed_behavior_has_e2e] The CLI journeys cover plan, no-op apply,
    // successful mutation, both drift refusals, source selection, missing Status, casing,
    // and paging. Transport errors remain the shared `graphql` boundary's behavior rather
    // than a new status-options behavior, and the pinned-schema test prevents valid GitHub
    // responses from entering the defensive malformed-response branches below.
    pub async fn status_options(
        &self,
        mode: StatusOptionsMode,
    ) -> Result<StatusOptionsReport, SourceError> {
        let before = self.status_snapshot().await?;
        let configured = self
            .statuses
            .targets
            .iter()
            // A terminal category's option is as configured as an open one's: a terminal
            // write validates it before closing and refuses when the board lacks it.
            .filter_map(|target| match target {
                StatusTarget::Column(name) | StatusTarget::Terminal(name, _) => {
                    Some(name.as_str().to_owned())
                }
                StatusTarget::Disabled => None,
            });
        let missing = configured
            .filter(|wanted| {
                !before
                    .options
                    .iter()
                    .any(|option| option.name.as_str().eq_ignore_ascii_case(wanted))
            })
            .collect::<Vec<_>>();
        let report = StatusOptionsReport {
            source: self.name.clone(),
            missing: missing.clone(),
            outcome: match (mode, missing.is_empty()) {
                (StatusOptionsMode::Plan, _) => StatusOptionsOutcome::Planned,
                (StatusOptionsMode::Apply, true) => StatusOptionsOutcome::Unchanged,
                (StatusOptionsMode::Apply, false) => StatusOptionsOutcome::Applied,
            },
            existing: before.options.clone(),
        };
        if mode == StatusOptionsMode::Plan || missing.is_empty() {
            return Ok(report);
        }
        let mut options = before
            .options
            .iter()
            .map(|option| {
                json!({
                    "id": option.id, "name": option.name, "color": option.color,
                    "description": option.description,
                })
            })
            .collect::<Vec<_>>();
        options.extend(missing.iter().map(|name| {
            json!({
                "name": name, "color": "GRAY", "description": ""
            })
        }));
        self.graphql(
            graphql::STATUS_OPTIONS_UPDATE,
            json!({"input": {
                "projectId": before.board_id, "fieldId": before.field_id,
                "singleSelectOptions": options,
            }}),
        )
        .await?;
        let after = self.status_snapshot().await?;
        let options_preserved = before
            .options
            .iter()
            .all(|old| after.options.iter().any(|new| new == old));
        let additions_present = missing.iter().all(|wanted| {
            after
                .options
                .iter()
                .any(|option| option.name.as_str().eq_ignore_ascii_case(wanted))
        });
        if !options_preserved || !additions_present || after.assignments != before.assignments {
            let recovery = serde_json::to_string_pretty(&before.assignments).map_err(|error| {
                SourceError::Malformed {
                    message: format!("cannot render pre-write Status recovery snapshot: {error}"),
                }
            })?;
            return Err(SourceError::Refused {
                message: format!(
                    "GitHub changed a pre-existing Status option id, name, color or description, or an item assignment after the guarded update; the pre-write item assignment snapshot is:\n{recovery}"
                ),
            });
        }
        Ok(report)
    }

    // llmlint: ignore-block[changed_behavior_has_e2e] Valid snapshot shapes are exercised through
    // the real CLI loopback journey, including pagination. The individual malformed guards
    // are defensive validation of a schema-pinned third-party response, not separate user
    // journeys; drift and missing-field failures cover the operation's recovery behavior.
    async fn status_snapshot(&self) -> Result<StatusSnapshot, SourceError> {
        let mut after: Option<String> = None;
        let mut snapshot: Option<StatusSnapshot> = None;
        loop {
            let data = self
                .graphql(
                    graphql::STATUS_OPTIONS_SNAPSHOT,
                    json!({
                        "owner": self.owner, "number": self.project_number,
                        "first": MAX_PAGE_SIZE, "after": after, "nestedFirst": MAX_PAGE_SIZE,
                    }),
                )
                .await?;
            let board = data
                .pointer("/owner/projectV2")
                .filter(|board| board.is_object())
                .ok_or_else(|| SourceError::Refused {
                    message: format!(
                        "source {} has no accessible GitHub Projects board",
                        self.name
                    ),
                })?;
            if board
                .pointer("/fields/pageInfo/hasNextPage")
                .and_then(Value::as_bool)
                != Some(false)
            {
                return Err(SourceError::Malformed {
                    message:
                        "GitHub project fields is incomplete or has malformed pageInfo.hasNextPage"
                            .into(),
                });
            }
            let field = board
                .pointer("/fields/nodes")
                .and_then(Value::as_array)
                .and_then(|fields| {
                    fields
                        .iter()
                        .find(|field| field.get("name").and_then(Value::as_str) == Some("Status"))
                })
                .ok_or_else(|| SourceError::Refused {
                    message: format!("source {} board has no Status field", self.name),
                })?;
            let options = field
                .get("options")
                .and_then(Value::as_array)
                .ok_or_else(|| SourceError::Malformed {
                    message: "GitHub Status field options is not an array".into(),
                })?
                .iter()
                .map(|option| {
                    Ok(StatusOption {
                        id: StatusOptionId::try_from(required_str(option, "id")?.to_owned())
                            .map_err(|message| SourceError::Malformed { message })?,
                        name: ColumnName::try_from(required_str(option, "name")?.to_owned())
                            .map_err(|message| SourceError::Malformed {
                                message: format!("GitHub Status option name is invalid: {message}"),
                            })?,
                        color: serde_json::from_value(
                            option.get("color").cloned().unwrap_or(Value::Null),
                        )
                        .map_err(|error| SourceError::Malformed {
                            message: format!("GitHub Status option color is invalid: {error}"),
                        })?,
                        description: optional_str(option, "description")?
                            .unwrap_or_default()
                            .to_owned(),
                    })
                })
                .collect::<Result<Vec<_>, SourceError>>()?;
            let board_id = required_nonblank_str(board, "id")?.to_owned();
            let field_id = required_nonblank_str(field, "id")?.to_owned();
            let current = snapshot.get_or_insert_with(|| StatusSnapshot {
                board_id,
                field_id,
                options,
                assignments: Vec::new(),
            });
            let items = board
                .pointer("/items/nodes")
                .and_then(Value::as_array)
                .ok_or_else(|| SourceError::Malformed {
                    message: "GitHub project items.nodes is not an array".into(),
                })?;
            for item in items {
                let field_values =
                    item.get("fieldValues")
                        .ok_or_else(|| SourceError::Malformed {
                            message: "GitHub project item is missing fieldValues".into(),
                        })?;
                if field_values
                    .pointer("/pageInfo/hasNextPage")
                    .and_then(Value::as_bool)
                    != Some(false)
                {
                    return Err(SourceError::Malformed {
                        message: "GitHub project item fieldValues is incomplete or has malformed pageInfo.hasNextPage".into(),
                    });
                }
                let values = item
                    .pointer("/fieldValues/nodes")
                    .and_then(Value::as_array)
                    .ok_or_else(|| SourceError::Malformed {
                        message: "GitHub project item fieldValues.nodes is not an array".into(),
                    })?;
                let status = values.iter().find(|value| {
                    value.pointer("/field/name").and_then(Value::as_str) == Some("Status")
                });
                current.assignments.push(StatusAssignment {
                    item_id: required_nonblank_str(item, "id")?.to_owned(),
                    option: status
                        .map(|value| {
                            Ok(AssignedStatusOption {
                                id: StatusOptionId::try_from(
                                    required_str(value, "optionId")?.to_owned(),
                                )
                                .map_err(|message| SourceError::Malformed { message })?,
                                name: ColumnName::try_from(required_str(value, "name")?.to_owned())
                                    .map_err(|message| SourceError::Malformed {
                                        message: format!(
                                            "GitHub assigned Status name is invalid: {message}"
                                        ),
                                    })?,
                            })
                        })
                        .transpose()?,
                });
            }
            let page = board.get("items").ok_or_else(|| SourceError::Malformed {
                message: "GitHub project is missing items".into(),
            })?;
            let has_next = page
                .pointer("/pageInfo/hasNextPage")
                .and_then(Value::as_bool)
                .ok_or_else(|| SourceError::Malformed {
                    message: "GitHub project items.pageInfo.hasNextPage is not a boolean".into(),
                })?;
            if !has_next {
                break;
            }
            let next =
                required_nonblank_str(page.get("pageInfo").unwrap_or(&Value::Null), "endCursor")?;
            validate_cursor_progress(after.as_deref(), next)?;
            after = Some(next.to_owned());
        }
        snapshot.ok_or_else(|| SourceError::Malformed {
            message: "GitHub returned no Status snapshot".into(),
        })
    }
    // llmlint: ignore-end[changed_behavior_has_e2e]

    /// Validate configuration and capture the named credential without exposing it.
    ///
    /// # Errors
    ///
    /// Returns [`SourceError::Config`] for a configuration this instance cannot use and
    /// [`SourceError::Auth`] when the named credential is missing or empty.
    pub fn new(
        name: &SourceName,
        config: GitHubProjectsConfig,
        secrets: &dyn SecretResolver,
    ) -> Result<Self, SourceError> {
        Self::recording_into(name, config, secrets, Arc::new(Accounting::new()))
    }

    /// The same, recording every request it sends into an accounting the caller holds too.
    ///
    /// [`Self::new`] is this with an accounting of its own. A caller that is also making
    /// its own calls to GitHub — a lane verifying a schema, sweeping residue or cleaning
    /// up — passes the one it records those into, so the session total accounts for the
    /// whole session rather than for this source's share of it.
    ///
    /// # Errors
    ///
    /// Exactly [`Self::new`]'s: [`SourceError::Config`] for a configuration this instance
    /// cannot use and [`SourceError::Auth`] when the named credential is missing or empty.
    pub fn recording_into(
        name: &SourceName,
        config: GitHubProjectsConfig,
        secrets: &dyn SecretResolver,
        ledger: Arc<Accounting>,
    ) -> Result<Self, SourceError> {
        if !valid_github_owner(&config.owner) {
            return Err(SourceError::Config {
                message: "owner must be 1-39 ASCII letters, digits, or single hyphens, and cannot start or end with a hyphen".into(),
            });
        }
        if config.project_number == 0 || config.project_number > i32::MAX as u32 {
            return Err(SourceError::Config {
                message: format!("project_number must be between 1 and {}", i32::MAX),
            });
        }
        if !valid_environment_name(&config.token_env) {
            return Err(SourceError::Config {
                message: "token_env must be a valid environment-variable name".into(),
            });
        }
        let repository = config
            .repository
            .as_deref()
            .map(RepositoryTarget::parse)
            .transpose()?;
        let endpoint = Url::parse(&config.endpoint).map_err(|e| SourceError::Config {
            message: format!("endpoint is not a valid URL: {e}"),
        })?;
        if endpoint.scheme() != "https"
            && !(endpoint.scheme() == "http"
                && endpoint
                    .host_str()
                    .is_some_and(|h| h == "127.0.0.1" || h == "localhost" || h == "::1"))
        {
            return Err(SourceError::Config {
                message:
                    "endpoint must use HTTPS (HTTP is accepted only for a loopback test server)"
                        .into(),
            });
        }
        let token = secrets.get(&config.token_env).filter(|token| !token.expose_secret().trim().is_empty()).ok_or_else(|| SourceError::Auth {
            message: format!("environment variable {} is missing or empty; set it to a fine-grained GitHub token granting Projects and Issues read/write plus Pull requests read-only access for every repository represented on the board", config.token_env),
        })?;
        Ok(Self {
            name: name.clone(),
            owner: config.owner,
            project_number: config.project_number,
            repository,
            endpoint,
            token,
            credential_name: config.token_env,
            statuses: StatusMapping::resolve(config.status_mapping, name)?,
            client: Client::builder()
                .user_agent("onetaskgraph")
                .build()
                .map_err(|e| SourceError::Config {
                    message: format!("cannot build HTTP client: {e}"),
                })?,
            created: Mutex::new(Vec::new()),
            pacing: Pacing::resolve(config.pacing, name)?,
            last_mutation: Mutex::new(None),
            board_cache: Mutex::new(None),
            search_cache: Mutex::new(None),
            fields_cache: Mutex::new(None),
            repository_cache: Mutex::new(BTreeMap::new()),
            ledger,
        })
    }

    /// A snapshot of every request this source has sent, and what each cost.
    ///
    /// A value to hold and compare rather than a borrow of the accounting itself, so two
    /// of them can sit side by side. When this source was built with
    /// [`Self::recording_into`] the snapshot is the whole shared session, which is the
    /// point of building it that way.
    #[must_use]
    pub fn accounting(&self) -> accounting::Session {
        self.ledger.snapshot()
    }

    /// Send one GraphQL document, pacing this source's own mutations and waiting out a
    /// rate limit rather than handing it straight back as an error.
    ///
    /// Retrying is safe for every document here, including the mutations, and the reason
    /// is that only a *refusal* is retried: [`Limiter::classify`] rules on a response
    /// GitHub sent, and a request GitHub refused for a rate limit did not run, so nothing
    /// this replays has already taken effect. An outcome this source cannot know — the
    /// send failed, or the body could not be read, so the mutation may well have landed —
    /// is [`Attempt::Failed`] in [`send_once`] and leaves this loop without a second
    /// attempt. A duplicate write would come from replaying one of those, and none is
    /// replayed.
    async fn graphql(&self, query: &str, variables: Value) -> Result<Value, SourceError> {
        let doing = operation_description(query);
        let mut waited = Duration::ZERO;
        let mut waits = 0_u32;
        let mut backoff = self.pacing.retry_backoff;
        loop {
            if is_mutation(query) {
                let spacing = self.reserve_mutation_slot();
                if !spacing.is_zero() {
                    tokio::time::sleep(spacing).await;
                }
            }
            let attempt = self.send_once(query, &variables).await;
            if is_mutation(query) {
                self.finish_mutation();
            }
            let limited = match attempt {
                Ok(data) => return Ok(data),
                Err(Attempt::Failed(error)) => return Err(error),
                Err(Attempt::Limited(limited)) => limited,
            };
            // GitHub really does send `retry-after: 0`, and retrying at once is the one
            // move that extends a secondary limit, so a hint below the schedule's own next
            // wait is raised to it.
            let wait = match limited.hint {
                Some(hint) => Duration::from_secs(hint).max(backoff),
                None => backoff,
            };
            let remaining = self.pacing.retry_budget.saturating_sub(waited);
            // A wait of nothing spends none of the budget, so it is exhaustion rather
            // than a retry. `Pacing::resolve` rules out every way of configuring one
            // except a budget of zero, where reporting the first refusal is the ask.
            if wait.is_zero() || wait > remaining {
                return Err(limited.exhausted(
                    doing,
                    waits,
                    waited,
                    wait,
                    self.pacing.retry_budget,
                ));
            }
            tokio::time::sleep(wait).await;
            waited += wait;
            waits += 1;
            backoff = backoff.saturating_mul(2);
        }
    }

    /// The next moment a content-creating mutation may leave this source, as a wait from
    /// now.
    ///
    /// The slot is reserved under the lock and the waiting happens outside it, so two
    /// callers take two slots rather than the same one — and no lock is held across an
    /// await.
    ///
    /// The moment it is spaced from is the previous mutation's *completion*, which
    /// [`Self::finish_mutation`] records. See that method for why the release moment on its
    /// own is the wrong thing to measure from.
    fn reserve_mutation_slot(&self) -> Duration {
        if self.pacing.min_mutation_interval.is_zero() {
            return Duration::ZERO;
        }
        // A poisoned lock here costs pacing, not correctness, and refusing the write over
        // it would turn an earlier failure into a second one for no gain.
        let mut last = self
            .last_mutation
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let now = Instant::now();
        // `checked_add` rather than `+`: `Instant + Duration` panics on overflow, and
        // pacing is not worth a panic even at a bound `MAX_PACING_MS` already rules out.
        let at = last.map_or(now, |previous| {
            previous
                .checked_add(self.pacing.min_mutation_interval)
                .map_or(now, |earliest| earliest.max(now))
        });
        *last = Some(at);
        at.saturating_duration_since(now)
    }

    /// Record that a content-creating mutation has finished, so the next one is spaced
    /// from here rather than from the moment this one was released.
    ///
    /// This source can only choose when a request *departs*; the limiter counts when it
    /// *arrives*, and the two differ by whatever the request spent in transit. Spacing one
    /// departure from the last therefore hands the limiter a gap of the interval less that
    /// transit, so a source pacing at 750 ms can still be seen arriving faster — which is
    /// exactly how a copy paced well inside a board's threshold was refused by it on a
    /// slower machine while passing on a quick one.
    ///
    /// Spacing from completion removes the subtraction rather than budgeting for it. The
    /// previous request had already arrived before its response came back, so its arrival
    /// is no later than this moment, and the next mutation is released at least the
    /// interval after this moment and arrives no earlier than it is released: the gap the
    /// limiter measures is therefore at least the interval, whatever transit costs and on
    /// whatever platform. The price is that a mutation's own round trip no longer counts
    /// towards its spacing, which makes this source slightly slower than the configured
    /// rate rather than slightly faster — the safe side of a limit that punishes being
    /// wrong by refusing reads for the next fifty minutes.
    ///
    /// A failed attempt is recorded too: a request refused by the limiter still arrived,
    /// and one that never left costs only a wait nobody needed.
    fn finish_mutation(&self) {
        if self.pacing.min_mutation_interval.is_zero() {
            return;
        }
        // A poisoned lock here costs pacing, not correctness, exactly as in the reservation.
        let mut last = self
            .last_mutation
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let now = Instant::now();
        // `max` rather than an assignment: a concurrent caller may already have reserved a
        // slot further out, and completing this request must never pull that slot back in.
        *last = Some(last.map_or(now, |reserved| reserved.max(now)));
    }

    /// One HTTP attempt, classified into an answer, a rate limit to wait out, or a
    /// failure that waiting cannot help — and recorded, whichever of the three it was.
    ///
    /// This is the one place a request leaves this crate, which is why the accounting is
    /// here rather than at each of the callers: a read path added later is counted without
    /// anybody remembering to count it, and
    /// `the_session_report_counts_every_request_the_board_served_and_what_each_cost` fails
    /// when one is not.
    async fn send_once(&self, query: &str, variables: &Value) -> Result<Value, Attempt> {
        let Attempted {
            result,
            limits,
            reported_cost,
        } = self.attempt(query, variables).await;
        // No `otherwise` name: every document this source sends is one of its own, and the
        // inventory gate on `graphql::DOCUMENTS` is what keeps that true.
        let sending = accounting::Request::graphql(query, variables, None, reported_cost);
        let outcome = match &result {
            Ok(_) => accounting::Outcome::Answered,
            Err(Attempt::Limited(_)) => accounting::Outcome::RateLimited,
            Err(Attempt::Failed(_)) => accounting::Outcome::Refused,
        };
        self.ledger.record(sending.finished(outcome, limits));
        result
    }

    /// The attempt itself, with what its response said about the rate limit alongside.
    ///
    /// The two are returned together rather than recorded here because every one of the
    /// early exits below is a different outcome, and a record written at each of them is a
    /// record one of them can be added without.
    async fn attempt(&self, query: &str, variables: &Value) -> Attempted {
        let mut limits = accounting::RateLimit::default();
        let mut reported_cost = None;
        let result = self
            .attempted(query, variables, &mut limits, &mut reported_cost)
            .await;
        Attempted {
            result,
            limits,
            reported_cost,
        }
    }

    /// One HTTP attempt, filling in what its response said about the rate limit as it goes.
    async fn attempted(
        &self,
        query: &str,
        variables: &Value,
        limits: &mut accounting::RateLimit,
        reported_cost: &mut Option<u64>,
    ) -> Result<Value, Attempt> {
        let response = self
            .client
            .post(self.endpoint.clone())
            .bearer_auth(self.token.expose_secret())
            .json(&json!({"query": query, "variables": variables}))
            .send()
            .await
            .map_err(|e| {
                Attempt::Failed(SourceError::Unavailable {
                    message: format!("GitHub GraphQL request failed: {e}"),
                })
            })?;
        let status = response.status();
        let header = |name: &str| whole_seconds(response.headers().get(name));
        *limits = accounting::RateLimit::read(|name| {
            response
                .headers()
                .get(name)
                .and_then(|value| value.to_str().ok())
                .map(str::to_owned)
        });
        // Exactly `0` is exhaustion and everything else — a count, an empty value, bytes
        // that are not text at all — is "not known to be exhausted". This never makes a
        // response a refusal on its own: it says which limiter a refusal is attributed to
        // and where its hint comes from, so a value this cannot read costs a hint rather
        // than an answer.
        let exhausted = response
            .headers()
            .get("x-ratelimit-remaining")
            .and_then(|value| value.to_str().ok())
            == Some("0");
        // `retry-after` is what GitHub asks for when it asks; when it does not and the
        // primary budget is spent, `x-ratelimit-reset` says when that budget comes back,
        // which is the same question answered as an absolute time. Nothing else here is a
        // hint, and a schedule is what answers a refusal that carries none.
        let hint = header("retry-after").or_else(|| {
            exhausted
                .then(|| header("x-ratelimit-reset"))
                .flatten()
                .map(|reset| reset.saturating_sub(Utc::now().timestamp().max(0).unsigned_abs()))
        });
        // Read before it is parsed, because the evidence which tells a secondary rate
        // limit from a rejected credential is in the body of a response whose status says
        // only "forbidden" — and a non-success response was never parsed at all.
        let body = response.text().await.map_err(|e| {
            Attempt::Failed(SourceError::Unavailable {
                message: format!("GitHub GraphQL response could not be read: {e}"),
            })
        })?;
        if let Some(limiter) = Limiter::classify(status, exhausted, &body) {
            return Err(Attempt::Limited(Limited { limiter, hint }));
        }
        if status == StatusCode::UNAUTHORIZED || status == StatusCode::FORBIDDEN {
            return Err(Attempt::Failed(SourceError::Auth {
                message: format!(
                    "GitHub rejected the configured credential with HTTP {status}; grant it Projects and Issues read/write plus Pull requests read-only access for every repository represented on the board"
                ),
            }));
        }
        if !status.is_success() {
            return Err(Attempt::Failed(SourceError::Unavailable {
                message: format!("GitHub GraphQL returned HTTP {status}"),
            }));
        }
        // GitHub reports what a call cost only when the document asked it to, and no
        // document this source sends does — so this is `None` here and carries the figure
        // for a caller whose own document selects `rateLimit { cost }`. What it must never
        // pick up is a `dryRun` probe's cost, which is some other document's.
        *reported_cost = serde_json::from_str::<Value>(&body)
            .ok()
            .as_ref()
            .and_then(|body| body.pointer("/data/rateLimit/cost"))
            .and_then(Value::as_u64);
        self.answer(&body).map_err(Attempt::Failed)
    }

    /// What one successful HTTP response says, once its GraphQL errors are read.
    fn answer(&self, body: &str) -> Result<Value, SourceError> {
        let body: Value = serde_json::from_str(body).map_err(|e| SourceError::Malformed {
            message: format!("GitHub returned invalid JSON: {e}"),
        })?;
        let errors = body
            .get("errors")
            .map(|value| {
                value.as_array().ok_or_else(|| SourceError::Malformed {
                    message: "GitHub response errors is not an array".into(),
                })
            })
            .transpose()?;
        if let Some(errors) = errors.filter(|errors| !errors.is_empty()) {
            let messages = errors
                .iter()
                .filter_map(|e| e.get("message").and_then(Value::as_str))
                .collect::<Vec<_>>()
                .join("; ");
            let message = if messages.is_empty() {
                "GitHub returned GraphQL errors".into()
            } else {
                messages
            };
            let normalized = message.to_ascii_lowercase();
            if normalized.contains("resource not accessible") || normalized.contains("scope") {
                return Err(SourceError::Auth {
                    message: format!(
                        "{message}; grant {} Projects and Issues read/write plus Pull requests read-only access for every repository represented on the board",
                        self.credential_name
                    ),
                });
            }
            return Err(SourceError::Refused { message });
        }
        body.get("data")
            .filter(|data| data.is_object())
            .cloned()
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub response has no data object".into(),
            })
    }

    // llmlint: ignore[boundary_inputs_validated] GitHub caps nested connections at 100 and
    // GraphQL cannot independently page them inside the outer item page. This source page is
    // deliberately bounded at that published maximum; the live drift journey exercises it.
    async fn board_page(
        &self,
        items_after: Option<&str>,
        items_first: u32,
    ) -> Result<Value, SourceError> {
        let data = self
            .graphql(
                graphql::BOARD,
                json!({"owner":self.owner,"number":self.project_number,
                       "first":items_first.min(MAX_PAGE_SIZE),"after":items_after,
                       "nestedFirst":NESTED_PAGE_SIZE,"duplicates":true}),
            )
            .await?;
        data.pointer("/owner/projectV2")
            .filter(|v| !v.is_null())
            .cloned()
            .ok_or_else(|| SourceError::Refused {
                message: format!(
                    "GitHub project {}/{} was not found or is not visible to the token",
                    self.owner, self.project_number
                ),
            })
    }

    /// The search that finds the issues of this board, narrowed by `also` when it is
    /// given.
    ///
    /// `project:owner/number` is what scopes a search to one board, and `is:issue` is what
    /// keeps pull requests out of it: GitHub's `ISSUE` search type covers both, and a pull
    /// request is somebody's change rather than a unit of plan. `-has:parent` is *not*
    /// here on purpose — GitHub accepts it and silently ignores it, so a project is told
    /// from a task by the `parent` field each issue carries rather than by the search.
    fn board_search(&self, also: Option<&str>) -> String {
        let scope = format!("project:{}/{} is:issue", self.owner, self.project_number);
        match also {
            Some(also) => format!("{scope} {also}"),
            None => scope,
        }
    }

    /// One issue this source reached directly, as the board item a read of the board would
    /// have produced — or `None` when this board does not hold it.
    ///
    /// The board half of an issue rides along on `Issue.projectItems`, so the value handed
    /// to [`Self::resolve`] is the very shape a `ProjectV2.items` read gives it: the board
    /// item's own id, that item's field values, and the issue as its content. One resolver
    /// for both routes is what makes an issue read through a search, through its own node
    /// id, or through its project's sub-issues report the same title, the same status, the
    /// same labels and the same qualified id.
    ///
    /// An issue with no entry for *this* board is not this source's to report, which is
    /// what keeps an id naming some other repository's issue from being answered as an item
    /// of this board. That answer is given about an **exhausted** connection and never
    /// about an unread page: the entry is looked for on the page in hand, and only if that
    /// page reports more of the connection, in [`Self::board_membership`]'s walk of the
    /// rest of it.
    async fn resolve_issue(&self, issue: &Value) -> Result<Option<Resolved>, SourceError> {
        if optional_str(issue, "__typename")? != Some("Issue") {
            return Ok(None);
        }
        let memberships = issue
            .get("projectItems")
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub issue is missing projectItems".into(),
            })?;
        let nodes = memberships
            .get("nodes")
            .and_then(Value::as_array)
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub issue projectItems.nodes is not an array".into(),
            })?;
        let held = match self.board_entry(nodes) {
            Some(held) => held.clone(),
            None => {
                let info = memberships
                    .get("pageInfo")
                    .ok_or_else(|| SourceError::Malformed {
                        message: "GitHub issue projectItems has no pageInfo".into(),
                    })?;
                // The page held no entry for this board. Whether that means the issue is
                // not on it is a question about the rest of the connection, and only a
                // connection with no rest answers it here.
                if !required_bool(info, "hasNextPage")? {
                    return Ok(None);
                }
                let cursor = required_str(info, "endCursor")?;
                validate_cursor_progress(None, cursor)?;
                let issue_id = required_str(issue, "id")?;
                match self.board_membership(issue_id, cursor).await? {
                    Some(held) => held,
                    None => return Ok(None),
                }
            }
        };
        let item = json!({
            "id": required_str(&held, "id")?,
            "project": held.get("project"),
            "fieldValues": held.get("fieldValues"),
            "content": issue,
        });
        self.resolve(&item)
    }

    /// This board's own entry among one page of an issue's `Issue.projectItems`.
    ///
    /// One spelling of *which membership is this board's*, so the page a read carries and
    /// the pages [`Self::board_membership`] walks are searched by the same rule.
    fn board_entry<'a>(&self, nodes: &'a [Value]) -> Option<&'a Value> {
        nodes.iter().find(|node| {
            node.pointer("/project/number").and_then(Value::as_u64)
                == Some(u64::from(self.project_number))
        })
    }

    /// The rest of one issue's board memberships, from `after`, for this board's entry.
    ///
    /// The recovery read: a page of memberships that holds no entry for this board says
    /// nothing about the memberships past it, so the connection is walked to exhaustion
    /// before an issue is reported as one this board does not hold. `Ok(None)` is that
    /// positive answer — the whole connection was read and no entry named this board —
    /// rather than a failure, and the walk is held to
    /// [`validate_cursor_progress`] like every other page walk here, so a source answering
    /// with a cursor that does not advance is refused instead of spun on.
    async fn board_membership(
        &self,
        issue: &str,
        after: &str,
    ) -> Result<Option<Value>, SourceError> {
        let mut after = after.to_owned();
        loop {
            let data = self
                .graphql(
                    graphql::ISSUE_BOARD_ITEMS,
                    json!({"id":issue,"first":MAX_PAGE_SIZE,"after":after,
                           "nestedFirst":NESTED_PAGE_SIZE}),
                )
                .await?;
            let Some(connection) = data
                .pointer("/node/projectItems")
                .filter(|value| !value.is_null())
            else {
                // The id resolved to nothing, or to something with no memberships to walk —
                // which is the same answer as a connection holding no entry for this board.
                return Ok(None);
            };
            let nodes = connection
                .get("nodes")
                .and_then(Value::as_array)
                .ok_or_else(|| SourceError::Malformed {
                    message: "GitHub issue projectItems.nodes is not an array".into(),
                })?;
            if let Some(held) = self.board_entry(nodes) {
                return Ok(Some(held.clone()));
            }
            let info = connection
                .get("pageInfo")
                .ok_or_else(|| SourceError::Malformed {
                    message: "GitHub issue projectItems has no pageInfo".into(),
                })?;
            let next = required_bool(info, "hasNextPage")?
                .then(|| required_str(info, "endCursor"))
                .transpose()?;
            match next {
                Some(next) => {
                    validate_cursor_progress(Some(&after), next)?;
                    after = next.to_owned();
                }
                None => return Ok(None),
            }
        }
    }

    /// One page of a board-scoped issue search, and where the next page resumes.
    async fn search_page(
        &self,
        search: &str,
        first: u32,
        after: Option<&str>,
    ) -> Result<(Vec<Resolved>, Option<String>), SourceError> {
        let data = self
            .graphql(
                graphql::SEARCH_ISSUES,
                json!({"search":search,"type":"ISSUE","first":first.min(MAX_PAGE_SIZE),
                       "after":after,"nestedFirst":NESTED_PAGE_SIZE,
                       "boardItems":BOARD_ITEMS_PAGE_SIZE,"duplicates":true}),
            )
            .await?;
        let connection = data.get("search").ok_or_else(|| SourceError::Malformed {
            message: "GitHub search response has no search connection".into(),
        })?;
        let mut found = Vec::new();
        for node in connection
            .get("nodes")
            .and_then(Value::as_array)
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub search nodes is not an array".into(),
            })?
        {
            if let Some(resolved) = self.resolve_issue(node).await? {
                found.push(resolved);
            }
        }
        let info = connection
            .get("pageInfo")
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub search connection has no pageInfo".into(),
            })?;
        let next = required_bool(info, "hasNextPage")?
            .then(|| required_str(info, "endCursor"))
            .transpose()?
            .map(str::to_owned);
        if let Some(next) = &next {
            validate_cursor_progress(after, next)?;
        }
        Ok((found, next))
    }

    /// Every issue this board holds, completed with what this run wrote.
    ///
    /// The completion is not an optimisation and it is not a cache: GitHub's issue search
    /// is an index and is eventually consistent, so an issue this run created seconds ago
    /// can be absent from it, and a project listed straight after being written would
    /// otherwise be missing from its own board. What is added back is only what this
    /// process itself wrote, out of [`Self::created`], which lives and dies with the
    /// process.
    async fn board_issues(&self) -> Result<Vec<Resolved>, SourceError> {
        let found = self.searched_issues().await?;
        self.completed_with_written(found, |_| true)
    }

    /// Every issue this board's own search reports, walked to exhaustion, read once per
    /// source.
    ///
    /// The uncompleted half of [`Self::board_issues`], separated because [`Self::board`]
    /// needs it too and the two would otherwise walk the same search twice in one command.
    /// See [`Self::search_cache`] for why holding it is the same bargain holding the board
    /// is.
    async fn searched_issues(&self) -> Result<Vec<Resolved>, SourceError> {
        let cached = self.search_cache()?.clone();
        if let Some(held) = cached {
            return Ok(held);
        }
        let mut after: Option<String> = None;
        let mut found = Vec::new();
        let search = self.board_search(None);
        loop {
            let (page, next) = self
                .search_page(&search, MAX_PAGE_SIZE, after.as_deref())
                .await?;
            found.extend(page);
            match next {
                Some(next) => after = Some(next),
                None => break,
            }
        }
        *self.search_cache()? = Some(found.clone());
        Ok(found)
    }

    /// This process's own view of the board's issues, or the refusal a poisoned lock is.
    fn search_cache(
        &self,
    ) -> Result<std::sync::MutexGuard<'_, Option<Vec<Resolved>>>, SourceError> {
        self.search_cache
            .lock()
            .map_err(|_| SourceError::Unavailable {
                message: "this source's view of the board's issues was left inconsistent by an \
                      earlier failure; next: run the command again"
                    .into(),
            })
    }

    /// `found`, with everything this run wrote that `keep` accepts and the read did not
    /// report.
    ///
    /// See [`Self::created`] and [`Self::board_issues`] for why a read has to be completed
    /// at all: the search index is behind, and a node read of an item filed moments ago can
    /// be too.
    fn completed_with_written(
        &self,
        mut found: Vec<Resolved>,
        keep: impl Fn(&Resolved) -> bool,
    ) -> Result<Vec<Resolved>, SourceError> {
        for own in self.created()?.iter().filter(|own| keep(own)) {
            if !found.iter().any(|item| item.id == own.id) {
                found.push(own.clone());
            }
        }
        Ok(found)
    }

    /// What resolving one node id reached.
    ///
    /// Three answers rather than an `Option`, because a board *draft* is none of the other
    /// two: it is not an issue, so the issue fragment reads nothing of it, and a read of one
    /// is completed by a read of the draft itself rather than reported as nothing.
    async fn reach(&self, id: &NativeId) -> Result<Reached, SourceError> {
        let asked = self
            .graphql(
                graphql::ISSUE,
                json!({"id":id.0,"nestedFirst":NESTED_PAGE_SIZE,
                       "boardItems":BOARD_ITEMS_PAGE_SIZE,"duplicates":true}),
            )
            .await;
        let data = match asked {
            Ok(data) => data,
            // A string that is not a node id at all is not a failure to report: it is an id
            // this board does not hold, which is what every read of one already answers.
            Err(error) if unresolvable_node(&error) => return Ok(Reached::Nothing),
            Err(error) => return Err(error),
        };
        let Some(node) = data.get("node").filter(|value| !value.is_null()) else {
            return Ok(Reached::Nothing);
        };
        if optional_str(node, "__typename")? == Some("DraftIssue") {
            return Ok(Reached::Draft);
        }
        Ok(match self.resolve_issue(node).await? {
            Some(item) => Reached::Held(Box::new(item)),
            None => Reached::Nothing,
        })
    }

    /// One item of this board by its own id, whatever kind it is.
    ///
    /// Resolved from the identifier alone: no search, board-wide or otherwise. What this
    /// run wrote is read first, because a node read of an item created moments ago can
    /// still be behind the board field values written onto it — see [`Self::created`].
    async fn item_by_id(&self, id: &NativeId) -> Result<Option<Resolved>, SourceError> {
        if let Some(own) = self.created()?.iter().find(|own| own.id == *id) {
            return Ok(Some(own.clone()));
        }
        match self.reach(id).await? {
            Reached::Held(item) => Ok(Some(*item)),
            Reached::Nothing => Ok(None),
            Reached::Draft => self.draft_by_id(id).await,
        }
    }

    /// One board draft by its own id, with the board item it sits in — or `None` when no
    /// item of this board is that draft's.
    ///
    /// The same decision [`Self::resolve_issue`] makes for an issue, over the draft's own
    /// `projectV2Items`: an entry naming this board is what makes it this board's. GitHub
    /// links a draft to one board item, so the page this read carries is the whole of that
    /// connection, and a page that reports more than it holds is refused rather than read
    /// as an answer about memberships nobody read.
    async fn draft_by_id(&self, id: &NativeId) -> Result<Option<Resolved>, SourceError> {
        let data = self
            .graphql(
                graphql::DRAFT,
                json!({"id":id.0,"nestedFirst":NESTED_PAGE_SIZE,
                       "boardItems":BOARD_ITEMS_PAGE_SIZE}),
            )
            .await?;
        // Gone between the two reads is an answer — the draft is no longer there. Anything
        // else than the draft [`Self::reach`] was just told this id is, is not one.
        let Some(draft) = data.get("node").filter(|node| !node.is_null()) else {
            return Ok(None);
        };
        if optional_str(draft, "__typename")? != Some("DraftIssue") {
            return Err(SourceError::Malformed {
                message: format!(
                    "GitHub answered {} as a draft and then as something else",
                    id.0
                ),
            });
        }
        if required_str(draft, "id")? != id.0 {
            return Err(SourceError::Malformed {
                message: format!("GitHub answered a different draft for {}", id.0),
            });
        }
        let memberships = draft
            .get("projectV2Items")
            .ok_or_else(|| SourceError::Malformed {
                message: format!("GitHub draft {} is missing projectV2Items", id.0),
            })?;
        let nodes = memberships
            .get("nodes")
            .and_then(Value::as_array)
            .ok_or_else(|| SourceError::Malformed {
                message: format!("GitHub draft {} projectV2Items.nodes is not an array", id.0),
            })?;
        let info = memberships
            .get("pageInfo")
            .ok_or_else(|| SourceError::Malformed {
                message: format!("GitHub draft {} projectV2Items has no pageInfo", id.0),
            })?;
        // Read whether or not this board's entry is on the page: a page claiming more than
        // the one item GitHub links a draft to is a malformed answer either way.
        if required_bool(info, "hasNextPage")? || nodes.len() > 1 {
            return Err(SourceError::Malformed {
                message: format!(
                    "GitHub draft {} reports more board items than the one GitHub links a draft \
                     to",
                    id.0
                ),
            });
        }
        if let Some(node) = nodes.first()
            && node
                .pointer("/project/number")
                .and_then(Value::as_u64)
                .is_none()
        {
            return Err(SourceError::Malformed {
                message: format!(
                    "GitHub draft {} board item has no numeric project number",
                    id.0
                ),
            });
        }
        let Some(held) = self.board_entry(nodes) else {
            return Ok(None);
        };
        if required_str(
            held.get("project").ok_or_else(|| SourceError::Malformed {
                message: format!("GitHub draft {} board item has no project", id.0),
            })?,
            "id",
        )? != self.board_fields().await?.id.as_str()
        {
            return Ok(None);
        }
        let item = json!({
            "id": required_str(held, "id")?,
            "project": held.get("project"),
            "fieldValues": held.get("fieldValues"),
            "content": draft,
        });
        self.resolve(&item)
    }

    /// The board's own id and field definitions, for a write whose item does not carry
    /// them — never its items.
    ///
    /// A board this command has already listed supplies them, since it read them beside its
    /// items; otherwise they come from [`graphql::BOARD_FIELDS`], once per command. Neither
    /// is consulted about which items the board holds: see the module documentation for
    /// why a question about one known item is answered by reading that item.
    async fn board_fields(&self) -> Result<BoardFields, SourceError> {
        if let Some(board) = self.board_cache()?.as_ref() {
            return Ok(BoardFields {
                id: BoardId::parse(&board.id)?,
                fields: board.fields.clone(),
            });
        }
        if let Some(held) = self.fields_cache()?.clone() {
            return Ok(held);
        }
        let data = self
            .graphql(
                graphql::BOARD_FIELDS,
                json!({"owner":self.owner,"number":self.project_number,
                       "nestedFirst":NESTED_PAGE_SIZE}),
            )
            .await?;
        let board = data
            .pointer("/boardFields/projectV2")
            .filter(|value| !value.is_null())
            .ok_or_else(|| SourceError::Refused {
                message: format!(
                    "GitHub project {}/{} was not found or is not visible to the token",
                    self.owner, self.project_number
                ),
            })?;
        let read = BoardFields {
            id: BoardId::parse(required_str(board, "id")?)?,
            fields: board.get("fields").cloned().unwrap_or(Value::Null),
        };
        *self.fields_cache()? = Some(read.clone());
        Ok(read)
    }

    /// This process's own view of the board's fields, or the refusal a poisoned lock is.
    fn fields_cache(&self) -> Result<std::sync::MutexGuard<'_, Option<BoardFields>>, SourceError> {
        self.fields_cache
            .lock()
            .map_err(|_| SourceError::Unavailable {
                message: "this source's view of the board's fields was left inconsistent by an \
                      earlier failure; next: run the command again"
                    .into(),
            })
    }

    /// What a write to `item` needs of the board, read off that item when it says enough and
    /// off [`Self::board_fields`] when it does not.
    ///
    /// A node read of an item names its board and carries the definition of every field it
    /// holds a value of — so an item naming its board, holding a value of the origin field,
    /// and, when the write carries a status, holding a `Status` value, needs no read of the
    /// board at all. **Nothing the item does not say is guessed:** a field it holds no value
    /// of may still be on the board, and a view reading it as absent would refuse a write the
    /// board can take or skip a field write the board needs, so such an item — and a create,
    /// which has no item yet — takes the board's fields from their own read instead.
    async fn fields_for(
        &self,
        item: Option<&Resolved>,
        writes_status: bool,
    ) -> Result<BoardFields, SourceError> {
        if let Some(item) = item
            && let Some(board_id) = item.named_board()
            && item.defines(ORIGIN_FIELD)
            && (!writes_status || item.defines("Status"))
        {
            return Ok(BoardFields {
                id: board_id,
                fields: json!({"nodes": item.fields, "pageInfo": {"hasNextPage": false}}),
            });
        }
        self.board_fields().await
    }

    /// Everything filed under one issue of this board, walked to exhaustion — or `None`
    /// when that id names nothing here with a sub-issue relationship to walk.
    ///
    /// `None` and an empty answer are different: `None` is *this is not an issue of this
    /// GitHub*, which is what sends a project selector on to be read as a name, and an
    /// empty vector is a project that holds nothing.
    async fn sub_issues(&self, id: &NativeId) -> Result<Option<Vec<Resolved>>, SourceError> {
        let mut after: Option<String> = None;
        let mut children = Vec::new();
        loop {
            let asked = self
                .graphql(
                    graphql::SUB_ISSUES,
                    json!({"id":id.0,"first":MAX_PAGE_SIZE,"after":after,
                           "nestedFirst":NESTED_PAGE_SIZE,
                           "boardItems":BOARD_ITEMS_PAGE_SIZE,"duplicates":true}),
                )
                .await;
            let data = match asked {
                Ok(data) => data,
                // A string that is not a node id at all is not a failure to report: it is
                // the ordinary answer to a selector naming a project by its name.
                Err(error) if unresolvable_node(&error) => return Ok(None),
                Err(error) => return Err(error),
            };
            let Some(connection) = data
                .pointer("/node/subIssues")
                .filter(|value| !value.is_null())
            else {
                // No such node, or one with no sub-issue relationship — a board draft is
                // the one this board can really hold.
                return Ok(None);
            };
            for node in connection
                .get("nodes")
                .and_then(Value::as_array)
                .ok_or_else(|| SourceError::Malformed {
                    message: "GitHub subIssues.nodes is not an array".into(),
                })?
            {
                if let Some(resolved) = self.resolve_issue(node).await? {
                    children.push(resolved);
                }
            }
            let info = connection
                .get("pageInfo")
                .ok_or_else(|| SourceError::Malformed {
                    message: "GitHub subIssues connection has no pageInfo".into(),
                })?;
            let next = required_bool(info, "hasNextPage")?
                .then(|| required_str(info, "endCursor"))
                .transpose()?;
            match next {
                Some(next) => {
                    validate_cursor_progress(after.as_deref(), next)?;
                    after = Some(next.to_owned());
                }
                None => return Ok(Some(children)),
            }
        }
    }

    /// Which issue of this board a project *name* is, or `None` when none is.
    ///
    /// One bounded query which filters on that name at the server, rather than a walk of
    /// every issue the board holds. The name is compared again here: the qualifier narrows
    /// what GitHub sends, and this source decides what it names.
    async fn project_by_name(&self, name: &str) -> Result<Option<NativeId>, SourceError> {
        let search = self.board_search(Some(&title_qualifier(name)));
        let (candidates, _) = self.search_page(&search, MAX_PAGE_SIZE, None).await?;
        Ok(candidates
            .into_iter()
            .find(|item| {
                item.kind == BoardKind::Work(ItemKind::Project)
                    && item.title.eq_ignore_ascii_case(name)
            })
            .map(|item| item.id))
    }

    /// Everything filed under one project of this board: the sub-issues of the issue that
    /// project is.
    ///
    /// Tasks *and* documents, because a document filed under a project is a sub-issue of it
    /// too — the caller keeps the kind it asked for. Nothing about this grows as the board
    /// gains projects, or as another project gains tasks.
    ///
    /// A qualified id names the issue and is asked for its sub-issues directly: one
    /// request, no search of any kind. Only a selector GitHub cannot resolve that way is
    /// read as a project *name*, which costs the one bounded search
    /// [`Self::project_by_name`] makes.
    async fn project_children(&self, selector: &NativeId) -> Result<Vec<Resolved>, SourceError> {
        let (project, children) = match self.sub_issues(selector).await? {
            Some(children) => (selector.clone(), children),
            None => match self.project_by_name(&selector.0).await? {
                Some(project) => {
                    let children = self.sub_issues(&project).await?.unwrap_or_default();
                    (project, children)
                }
                None => return Ok(Vec::new()),
            },
        };
        self.completed_with_written(children, |own| own.parent.as_ref() == Some(&project))
    }

    /// Every item on the board: the union of both enumerations GitHub offers of one.
    ///
    /// Neither contains the other, so neither is dropped — only `ProjectV2.items` lists a
    /// board **draft** and reads the board's own fields beside its items, and only the search
    /// reports an item that connection is behind on. The module documentation is where the lag and the
    /// measurements behind it are written down.
    ///
    /// A search result is admitted on the same terms as any other issue this source reaches
    /// directly — [`Self::resolve_issue`] keeps it only if that issue's own `projectItems`
    /// names *this* board — so an issue the index still believes is here after it was taken
    /// off is refused rather than reported.
    ///
    /// See [`Self::board_cache`]. Both completions happen on every call rather than once,
    /// which is what the cache could otherwise have broken.
    async fn board(&self) -> Result<Board, SourceError> {
        let cached = self.board_cache()?.clone();
        let mut board = match cached {
            Some(board) => board,
            None => {
                let read = self.read_board().await?;
                *self.board_cache()? = Some(read.clone());
                read
            }
        };
        for held in self.searched_issues().await? {
            if !board.items.iter().any(|item| item.id == held.id) {
                board.items.push(held);
            }
        }
        for own in self.created()?.iter() {
            if !board.items.iter().any(|item| item.id == own.id) {
                board.items.push(own.clone());
            }
        }
        Ok(board)
    }

    /// This process's own view of the board, or the refusal a poisoned lock is.
    fn board_cache(&self) -> Result<std::sync::MutexGuard<'_, Option<Board>>, SourceError> {
        self.board_cache
            .lock()
            .map_err(|_| SourceError::Unavailable {
                message: "this source's view of the board was left inconsistent by an earlier \
                      failure; next: run the command again"
                    .into(),
            })
    }

    /// Bring this process's own view of the board up to an item it has just written.
    ///
    /// A created item goes to `created`, which is what completes a board read GitHub's own
    /// eventual consistency has left behind. An item that was already there is replaced
    /// where it sits, so a second write of it in the same command reads its real parent
    /// rather than the one it had before the first write.
    ///
    /// "Where it sits" is three places, and missing an earlier one leaves a stale record
    /// that wins: an item this same run created is held in `created` and not in the cached
    /// board, and `board` completes the cached board *from* `created`, so replacing only
    /// the cached copy of such an item replaces nothing and the read still reports the
    /// title it was created with. The search is the third, and it is the one an item the
    /// board's own projection is behind on sits in *alone* — which is exactly the item this
    /// source is least able to re-read, so leaving it out would put the stale title back on
    /// the only items the completion in [`Self::board`] exists for.
    fn remember_written(&self, item: Resolved, created: bool) -> Result<(), SourceError> {
        if created {
            self.created()?.push(item);
            return Ok(());
        }
        {
            let mut own = self.created()?;
            if let Some(held) = own.iter_mut().find(|held| held.id == item.id) {
                *held = item;
                return Ok(());
            }
        }
        if let Some(board) = self.board_cache()?.as_mut()
            && let Some(held) = board.items.iter_mut().find(|held| held.id == item.id)
        {
            *held = item.clone();
        }
        if let Some(found) = self.search_cache()?.as_mut()
            && let Some(held) = found.iter_mut().find(|held| held.id == item.id)
        {
            *held = item;
        }
        Ok(())
    }

    /// Forget one item this process has just deleted, from every half of its own view.
    fn forget(&self, id: &NativeId) -> Result<(), SourceError> {
        self.created()?.retain(|own| own.id != *id);
        if let Some(board) = self.board_cache()?.as_mut() {
            board.items.retain(|item| item.id != *id);
        }
        if let Some(found) = self.search_cache()?.as_mut() {
            found.retain(|item| item.id != *id);
        }
        Ok(())
    }

    /// Every page of the board, read from GitHub.
    async fn read_board(&self) -> Result<Board, SourceError> {
        let mut after: Option<String> = None;
        let mut items = Vec::new();
        let mut board;
        loop {
            let page = self.board_page(after.as_deref(), MAX_PAGE_SIZE).await?;
            for item in page
                .pointer("/items/nodes")
                .and_then(Value::as_array)
                .ok_or_else(|| SourceError::Malformed {
                    message: "GitHub project items.nodes is not an array".into(),
                })?
            {
                if let Some(resolved) = self.resolve(item)? {
                    items.push(resolved);
                }
            }
            let info = page
                .pointer("/items/pageInfo")
                .ok_or_else(|| SourceError::Malformed {
                    message: "GitHub project items have no pageInfo".into(),
                })?;
            let has_next = required_bool(info, "hasNextPage")?;
            let next = has_next
                .then(|| required_str(info, "endCursor"))
                .transpose()?;
            board = page.clone();
            match next {
                Some(next) => {
                    validate_cursor_progress(after.as_deref(), next)?;
                    after = Some(next.to_owned());
                }
                None => break,
            }
        }
        Ok(Board {
            id: required_str(&board, "id")?.to_owned(),
            fields: board.get("fields").cloned().unwrap_or(Value::Null),
            items,
        })
    }

    /// The items this source has created, for completing a board read that is behind.
    fn created(&self) -> Result<std::sync::MutexGuard<'_, Vec<Resolved>>, SourceError> {
        self.created.lock().map_err(|_| SourceError::Unavailable {
            message: "this source's record of what it created in this run was left \
                      inconsistent by an earlier failure; next: run the command again"
                .into(),
        })
    }

    /// One board item as this source reports it, or `None` for content it ignores.
    ///
    /// A pull request is neither a project nor a task — it is somebody's change, not a
    /// unit of plan — and an item whose content the token cannot see has nothing to
    /// report at all.
    fn resolve(&self, item: &Value) -> Result<Option<Resolved>, SourceError> {
        let content = item.get("content").ok_or_else(|| SourceError::Malformed {
            message: "GitHub project item is missing content".into(),
        })?;
        if content.is_null() {
            return Ok(None);
        }
        let content_kind = match required_str(content, "__typename")? {
            "Issue" => ContentKind::Issue,
            "DraftIssue" => ContentKind::DraftIssue,
            _ => return Ok(None),
        };
        let field_values = item
            .get("fieldValues")
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub project item is missing fieldValues".into(),
            })?;
        complete_connection(field_values, "project item field values", NESTED_PAGE_SIZE)?;
        let nodes = field_values
            .get("nodes")
            .and_then(Value::as_array)
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub project item fieldValues.nodes is not an array".into(),
            })?;
        if let Some(labels) = content.get("labels") {
            complete_connection(labels, "content labels", NESTED_PAGE_SIZE)?;
        }
        let raw_body = optional_str(content, "body")?.map(str::to_owned);
        let (body, slot) = metadata_body(raw_body.clone())?;
        let parent = optional_str(content.get("parent").unwrap_or(&Value::Null), "id")?
            .map(|id| NativeId(id.to_owned()));
        // A draft has no sub-issues to summarise, and GitHub's schema gives it no field
        // to read one from; it is a task, and never a project.
        let sub_issues = match content_kind {
            ContentKind::Issue => sub_issue_total(content)?,
            ContentKind::DraftIssue => 0,
        };
        let content_id = required_str(content, "id")?;
        let marked = ItemKind::from_metadata(&slot).map_err(|message| SourceError::Malformed {
            message: format!("GitHub issue {content_id}: {message}"),
        })?;
        let raw_title = required_str(content, "title")?;
        // The design prefix is read *first*, before either of the two rules that separate
        // a project from a task. A document is not work whatever sub-issues it has and
        // whatever marker it carries, and reading the prefix later would make a design
        // issue with none of either an empty project.
        let kind = if raw_title.starts_with(DESIGN_TITLE_PREFIX) {
            BoardKind::Document
        } else if parent.is_some() {
            // Being a sub-issue wins outright, and no marker overrides it: an issue filed
            // under a project is that project's task even when it has sub-issues of its
            // own.
            BoardKind::Work(ItemKind::Task)
        } else if sub_issues > 0 || marked == Some(ItemKind::Project) {
            BoardKind::Work(ItemKind::Project)
        } else {
            BoardKind::Work(ItemKind::Task)
        };
        // The title a person wrote, which for a document is the one without the prefix —
        // the same way `content` above is the body without this source's metadata slot.
        let title = match kind {
            BoardKind::Document => raw_title[DESIGN_TITLE_PREFIX.len()..].to_owned(),
            BoardKind::Work(_) => raw_title.to_owned(),
        };
        let own_repository = content
            .pointer("/repository/nameWithOwner")
            .and_then(Value::as_str)
            .map(|origin| Repository::try_from(format!("{}/{origin}", RepositoryTarget::HOST)))
            .transpose()
            .map_err(|message| SourceError::Malformed { message })?;
        let repositories = if slot.contains_key(Repository::METADATA_KEY) {
            Repository::from_metadata(&slot)
                .map_err(|message| SourceError::Malformed { message })?
        } else {
            own_repository.clone().into_iter().collect()
        };
        let id = NativeId(content_id.to_owned());
        // Read only for a task, because only a task has either list: a project or a
        // document holding one of these keys holds nothing this source reports, and the
        // keys are left out of its caller-visible metadata all the same.
        let (delivers, delivered_by) = if kind == BoardKind::Work(ItemKind::Task) {
            let listed = |key: &str| {
                TaskRef::from_value(key, &id, Some(&self.name), slot.get(key))
                    .map_err(|message| SourceError::Malformed { message })
            };
            (
                listed(TaskRef::DELIVERS_KEY)?,
                listed(TaskRef::DELIVERED_BY_KEY)?,
            )
        } else {
            (Vec::new(), Vec::new())
        };
        let (option, closed, reason) = Self::status_parts(nodes, content)?;
        Ok(Some(Resolved {
            item_id: required_str(item, "id")?.to_owned(),
            id,
            content_kind,
            kind,
            title,
            body: body.filter(|value| !value.is_empty()),
            raw_body,
            status: self.statuses.status(option, closed, reason),
            option: option.map(str::to_owned),
            closed,
            delivers,
            delivered_by,
            labels: labels(content)?,
            parent,
            origin: text_field(nodes, ORIGIN_FIELD)?.filter(|value| !value.is_empty()),
            number: match content_kind {
                ContentKind::Issue => Some(issue_number(content)?),
                // A draft is filed in no repository, so nothing ever numbered it:
                // `DraftIssue` declares no `number` at all, exactly as it declares no
                // `subIssuesSummary` the branch above reads.
                ContentKind::DraftIssue => None,
            },
            url: optional_str(content, "url")?.map(str::to_owned),
            created_at: optional_time(content, "createdAt")?,
            updated_at: optional_time(content, "updatedAt")?,
            own_repository,
            repositories,
            slot,
            // Present when the item was reached through its own issue, whose board entry
            // names the board; a read of the board's own items has the board already. An
            // empty id names nothing a field write could address, so it is read as absent and
            // the write goes back to reading the board.
            board_id: item
                .pointer("/project/id")
                .and_then(Value::as_str)
                .filter(|id| !id.is_empty())
                .map(str::to_owned),
            fields: field_definitions(nodes),
        }))
    }

    /// What one board item's status is read from: its `Status` option, whether its issue
    /// is closed, and the reason it was closed with. [`StatusMapping::status`] turns the
    /// three into the status it reports.
    fn status_parts<'a>(
        field_values: &'a [Value],
        content: &'a Value,
    ) -> Result<(Option<&'a str>, bool, Option<&'a str>), SourceError> {
        let option = field_values
            .iter()
            .find(|value| value.pointer("/field/name").and_then(Value::as_str) == Some("Status"))
            .map(|value| required_str(value, "name"))
            .transpose()?;
        let closed = optional_str(content, "state")? == Some("CLOSED");
        Ok((option, closed, optional_str(content, "stateReason")?))
    }

    /// The board Status option this write selects, or the refusal that says why not.
    ///
    /// The mapped option is required for both open and terminal targets. A terminal write
    /// validates it before changing either representation, so it can never fall back to
    /// closing an issue whose board cannot display the matching status.
    ///
    /// Answers the field's id, the option's id, and the option's name as the board spells
    /// it — which is the name a read of the item reports once it sits there.
    fn column_for(
        &self,
        fields: &Value,
        status: &Status,
        target: &StatusTarget,
    ) -> Result<Option<(String, String, String)>, SourceError> {
        let wanted = match target {
            StatusTarget::Column(wanted) | StatusTarget::Terminal(wanted, _) => wanted.as_str(),
            StatusTarget::Disabled => return Ok(None),
        };
        let missing = |detail: &str| SourceError::Refused {
            message: format!(
                "status {} of source {} needs the board Status option {wanted:?}, and {detail};                  add that option to the board, or point status_mapping.{} of this source at one                  it has",
                category_name(status.category),
                self.name,
                category_name(status.category)
            ),
        };
        let Some(field) = Board::field(fields, "Status")? else {
            return Err(missing("this board has no Status field"));
        };
        if required_str(field, "__typename")? != "ProjectV2SingleSelectField" {
            return Err(missing(
                "this board's Status field is not a single-select field",
            ));
        }
        let option = field
            .get("options")
            .and_then(Value::as_array)
            .and_then(|options| {
                options.iter().find(|option| {
                    option
                        .get("name")
                        .and_then(Value::as_str)
                        .is_some_and(|name| name.eq_ignore_ascii_case(wanted))
                })
            });
        match option {
            None => Err(missing("this board does not have it")),
            Some(option) => Ok(Some((
                required_str(field, "id")?.to_owned(),
                required_str(option, "id")?.to_owned(),
                required_str(option, "name")?.to_owned(),
            ))),
        }
    }

    /// The refusal a status that closes an issue is answered with over a board draft.
    fn closes_a_draft(&self, category: StatusCategory) -> SourceError {
        SourceError::Refused {
            message: format!(
                "status {} of source {} closes the item's issue, and GitHub draft items have \
                 no open or closed state",
                category_name(category),
                self.name
            ),
        }
    }

    /// What a status write to one item needs of the board: the board's id and the
    /// definition of its `Status` field, read off the item when the item says both.
    ///
    /// The same reasoning as [`Self::fields_for`]: a node read of the item names its board,
    /// and its `Status` value carries that field's definition, options and all. An item that
    /// does not say — no board id, or no `Status` value to read the field off — takes them
    /// from [`Self::board_fields`], which reads no item.
    async fn status_board(&self, item: &Resolved) -> Result<BoardFields, SourceError> {
        if item.defines("Status")
            && let Some(board_id) = item.named_board()
        {
            return Ok(BoardFields {
                id: board_id,
                fields: json!({"nodes": item.fields, "pageInfo": {"hasNextPage": false}}),
            });
        }
        self.board_fields().await
    }

    /// Set one task's status and nothing else; see [`TaskSource::set_task_status`].
    async fn set_status(
        &self,
        id: &NativeId,
        category: StatusCategory,
    ) -> Result<Option<Status>, SourceError> {
        // Refused before anything is read, in the words a write of the same status is.
        let target = self.resolved_target(category)?;
        let Some(mut item) = self
            .item_by_id(id)
            .await?
            .filter(|item| item.kind == BoardKind::Work(ItemKind::Task))
        else {
            return Ok(None);
        };
        let board = self.status_board(&item).await?;
        let wanted = Status {
            category,
            name: category_name(category).to_owned(),
        };
        let (field, option, name) = self
            .column_for(&board.fields, &wanted, &target)?
            .ok_or_else(|| SourceError::Malformed {
                message: format!(
                    "status {} of source {} names no board Status option",
                    category_name(category),
                    self.name
                ),
            })?;
        match &target {
            StatusTarget::Terminal(_, reason) => {
                if item.content_kind == ContentKind::DraftIssue {
                    return Err(self.closes_a_draft(category));
                }
                self.set_item_field(
                    board.id.as_str(),
                    &item.item_id,
                    &field,
                    json!({"singleSelectOptionId": option}),
                )
                .await?;
                self.update_content(
                    ContentKind::Issue,
                    &item.id,
                    json!({"stateInput": state_input(Some(&target))}),
                )
                .await?;
                item.closed = true;
                item.status = self
                    .statuses
                    .status(Some(&name), true, Some(reason.reason()));
                item.option = Some(name);
            }
            StatusTarget::Column(_) => {
                // An option is what an open item's status is, so a closed issue is reopened
                // first — sitting closed in the column, it would read back as closed. A draft has
                // no state to reopen.
                if item.content_kind == ContentKind::Issue && item.closed {
                    self.update_content(
                        ContentKind::Issue,
                        &item.id,
                        json!({"stateInput": state_input(Some(&target))}),
                    )
                    .await?;
                    item.closed = false;
                }
                self.set_item_field(
                    board.id.as_str(),
                    &item.item_id,
                    &field,
                    json!({"singleSelectOptionId": option}),
                )
                .await?;
                item.status = self.statuses.status(Some(&name), false, None);
                item.option = Some(name);
            }
            StatusTarget::Disabled => unreachable!("resolved_target refused a disabled status"),
        }
        let status = item.status.clone();
        self.remember_written(item, false)?;
        Ok(Some(status))
    }

    /// Replace one task's `delivered_by` and nothing else; see
    /// [`TaskSource::set_delivered_by`].
    ///
    /// One update of the body, which differs from the body GitHub holds only inside the
    /// metadata slot — see [`with_slot`]. A body that would not change is not sent at all.
    async fn replace_delivered_by(
        &self,
        id: &NativeId,
        delivered_by: &[TaskRef],
    ) -> Result<Option<()>, SourceError> {
        let entries = TaskRef::listed(
            TaskRef::DELIVERED_BY_KEY,
            id,
            Some(&self.name),
            delivered_by.to_vec(),
        )
        .map_err(|message| SourceError::Refused { message })?;
        let Some(mut item) = self
            .item_by_id(id)
            .await?
            .filter(|item| item.kind == BoardKind::Work(ItemKind::Task))
        else {
            return Ok(None);
        };
        let mut slot = item.slot.clone();
        set_task_list(&mut slot, TaskRef::DELIVERED_BY_KEY, &entries);
        self.write_slot(&mut item, &slot).await?;
        item.delivered_by = entries;
        self.remember_written(item, false)?;
        Ok(Some(()))
    }

    /// Set one caller key of the metadata slot of one issue of `kind`, and nothing else;
    /// see [`TaskSource::set_task_metadata`].
    ///
    /// `None` when this board holds no item by that id, or holds one of another kind. The
    /// answer is the item as this source now reads it, so what a caller is told the key
    /// holds is what the slot holds.
    ///
    /// A key already holding the value is answered without a write, compared as JSON rather
    /// than as the body's bytes: a slot a person spelled with other whitespace would
    /// otherwise be re-encoded, which is a write that changes nothing the caller asked for.
    async fn set_slot_key(
        &self,
        id: &NativeId,
        kind: BoardKind,
        key: &MetadataKey,
        value: &Value,
    ) -> Result<Option<Resolved>, SourceError> {
        let Some(mut item) = self.item_by_id(id).await?.filter(|item| item.kind == kind) else {
            return Ok(None);
        };
        if item.slot.get(key.as_str()) == Some(value) {
            return Ok(Some(item));
        }
        let mut slot = item.slot.clone();
        slot.insert(key.as_str().to_owned(), value.clone());
        self.write_slot(&mut item, &slot).await?;
        self.remember_written(item.clone(), false)?;
        Ok(Some(item))
    }

    /// Put `slot` in one item's metadata slot with a single update of its body, and bring
    /// `item` up to what that write left.
    ///
    /// The body sent differs from the body GitHub holds only inside the slot — see
    /// [`with_slot`] — and a body that would not change is not sent at all. It goes through
    /// the mutation the item's content takes, so a board draft's body is written with
    /// `updateProjectV2DraftIssue` exactly as an issue's is with `updateIssue`.
    async fn write_slot(
        &self,
        item: &mut Resolved,
        slot: &BTreeMap<String, Value>,
    ) -> Result<(), SourceError> {
        let held = item.raw_body.clone().unwrap_or_default();
        let body = with_slot(&held, slot)?;
        if body != held {
            self.update_content(item.content_kind, &item.id, json!({"body": body}))
                .await?;
        }
        let (visible, slot) = metadata_body(Some(body.clone()))?;
        item.body = visible.filter(|value| !value.is_empty());
        item.raw_body = Some(body);
        item.slot = slot;
        Ok(())
    }

    /// This instance's target for a category, refusing one it has disabled.
    ///
    /// Nothing here mutates the board's option set to make room for a status. GitHub
    /// documents `UpdateProjectV2FieldInput.singleSelectOptions` as *"provided values
    /// overwrite existing options"*, so no addition is additive and a mistake destroys the
    /// field and every item's status.
    fn resolved_target(&self, category: StatusCategory) -> Result<StatusTarget, SourceError> {
        let target = self.statuses.target(category).clone();
        if target != StatusTarget::Disabled {
            return Ok(target);
        }
        Err(SourceError::Refused {
            message: if category == StatusCategory::Draft {
                format!(
                    "status draft is disabled for source {}: draft is incompatible with this \
                     integration because GitHub draft issues cannot have sub-issues, and this \
                     source stores a project's tasks as its issue's sub-issues",
                    self.name
                )
            } else if category == StatusCategory::Unknown {
                format!(
                    "status {} is disabled for source {}; set status_mapping.{} of this source \
                     to one board Status option name; every word classified unknown is written \
                     to that one option",
                    category_name(category),
                    self.name,
                    category_name(category)
                )
            } else {
                format!(
                    "status {} is disabled for source {}; set status_mapping.{} of this source \
                     to a board Status option name",
                    category_name(category),
                    self.name,
                    category_name(category)
                )
            },
        })
    }

    async fn set_item_field(
        &self,
        board_id: &str,
        item_id: &str,
        field_id: &str,
        value: Value,
    ) -> Result<(), SourceError> {
        let data = self
            .graphql(
                graphql::UPDATE_FIELD,
                json!({"input":{
                    "projectId":board_id,"itemId":item_id,"fieldId":field_id,"value":value
                }}),
            )
            .await?;
        let returned = data
            .pointer("/updateProjectV2ItemFieldValue/projectV2Item")
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub field update returned no project item".into(),
            })?;
        if required_str(returned, "id")? != item_id {
            return Err(SourceError::Malformed {
                message: "GitHub field update returned the wrong project item".into(),
            });
        }
        Ok(())
    }

    async fn native_dependency_ids(&self, id: &NativeId) -> Result<Vec<String>, SourceError> {
        let mut after: Option<String> = None;
        let mut ids = Vec::new();
        loop {
            let data = self
                .graphql(
                    graphql::ISSUE_DEPENDENCIES,
                    json!({"id":id.0,"first":MAX_PAGE_SIZE,"after":after}),
                )
                .await?;
            let connection =
                data.pointer("/node/blockedBy")
                    .ok_or_else(|| SourceError::Malformed {
                        message: "GitHub dependency response has no blockedBy connection".into(),
                    })?;
            ids.extend(
                connection
                    .get("nodes")
                    .and_then(Value::as_array)
                    .ok_or_else(|| SourceError::Malformed {
                        message: "GitHub dependency response nodes is not an array".into(),
                    })?
                    .iter()
                    .map(|value| required_str(value, "id").map(str::to_owned))
                    .collect::<Result<Vec<_>, _>>()?,
            );
            let next = next_cursor(connection)?;
            if let Some(next) = &next {
                validate_cursor_progress(after.as_deref(), &next.0)?;
            }
            after = next.map(|cursor| cursor.0);
            if after.is_none() {
                return Ok(ids);
            }
        }
    }

    async fn dependencies(
        &self,
        id: &NativeId,
        near_kind: ItemKind,
        direction: Direction,
        page: &PageRequest,
    ) -> Result<Page<DependencyEdge>, SourceError> {
        validate_page(page)?;
        let limit = page.limit.min(MAX_PAGE_SIZE) as usize;
        let cursor = page.cursor.as_ref().map(|c| c.0.as_str());
        let recorded = recorded_offset(cursor, direction)?;
        // Asked for even in the recorded phase, whose page reads nothing from the
        // connection: `__typename` is what says whether this item has a native
        // relationship at all, and that is what decides which far ends the reserved key is
        // allowed to hold.
        let data = self
            .graphql(
                graphql::ISSUE_DEPENDENCIES,
                json!({"id":id.0,"first":page.limit.min(MAX_PAGE_SIZE),
                       "after":if recorded.is_some() {None} else {cursor}}),
            )
            .await?;
        let node =
            data.get("node")
                .filter(|v| !v.is_null())
                .ok_or_else(|| SourceError::Refused {
                    message: format!(
                        "GitHub item {} was not found or does not support dependencies",
                        id.0
                    ),
                })?;
        let connection_name = match direction {
            Direction::DependsOn => "blockedBy",
            Direction::DependedOnBy => "blocking",
        };
        // A draft has neither `blockedBy` nor `blocking`, so nothing it depends on can be
        // named natively and the reserved key may hold any far end. An issue's connections
        // hold issues, and this source reads them at the near item's own level.
        let natively_names = (required_str(node, "__typename")? == "Issue").then_some(near_kind);
        if let Some(offset) = recorded {
            return Ok(recorded_page(
                self.recorded_edges(id, near_kind, direction, natively_names, node)
                    .await?,
                offset,
                limit,
            ));
        }
        if natively_names.is_none() {
            return Ok(recorded_page(
                self.recorded_edges(id, near_kind, direction, natively_names, node)
                    .await?,
                0,
                limit,
            ));
        }
        let connection = node
            .get(connection_name)
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub dependency response is missing its connection".into(),
            })?;
        let nodes = connection
            .get("nodes")
            .and_then(Value::as_array)
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub dependency response nodes is not an array".into(),
            })?;
        // `from` depends on `to`, always. GitHub spells the same relationship from either
        // end — `blockedBy` lists what this item waits on, `blocking` lists what waits on
        // it — so the near item is `from` in one direction and `to` in the other.
        let items = nodes
            .iter()
            .map(|value| {
                let related = NativeId(required_str(value, "id")?.into());
                let related_kind = related_kind(value)?;
                let (from, to) = match direction {
                    Direction::DependsOn => (
                        DependencyEndpoint::from_native(id.clone(), near_kind),
                        DependencyEndpoint::from_native(related, related_kind),
                    ),
                    Direction::DependedOnBy => (
                        DependencyEndpoint::from_native(related, related_kind),
                        DependencyEndpoint::from_native(id.clone(), near_kind),
                    ),
                };
                Ok(DependencyEdge {
                    from,
                    to,
                    kind: DependencyKind::Blocks,
                })
            })
            .collect::<Result<Vec<_>, SourceError>>()?;
        let mut next = next_cursor(connection)?;
        if let Some(next) = &next {
            validate_cursor_progress(cursor, &next.0)?;
        }
        if next.is_none()
            && !self
                .recorded_edges(id, near_kind, direction, natively_names, node)
                .await?
                .is_empty()
        {
            next = Some(Cursor(format!("{RECORDED_CURSOR}0")));
        }
        Ok(Page { items, next })
    }

    /// The edges this item records under [`DependencyEdge::RECORDED_KEY`], which is where
    /// a far end in another source has to live: no GitHub issue relationship can name one.
    ///
    /// Only forwards. The reverse of a recorded edge is derived from the far end, and this
    /// source never writes one down.
    ///
    /// The metadata lives in the item's own body slot, and `node` is the dependency read's
    /// own answer, which carries an issue's body — so an issue's recorded edges cost no
    /// request beyond the read already made, and reading the board for them would be a
    /// walk of every item for one field of one. A draft has no body in that answer, because
    /// a draft is not an issue, so a draft's are read off its own read by id — never off a
    /// listing of the board, which can be behind on the very item asked about.
    async fn recorded_edges(
        &self,
        id: &NativeId,
        near_kind: ItemKind,
        direction: Direction,
        natively_names: Option<ItemKind>,
        node: &Value,
    ) -> Result<Vec<DependencyEdge>, SourceError> {
        if direction != Direction::DependsOn {
            return Ok(Vec::new());
        }
        let slot = match node.get("body") {
            Some(body) if natively_names.is_some() => {
                metadata_body(body.as_str().map(str::to_owned))?.1
            }
            _ => {
                let Some(item) = self.item_by_id(id).await? else {
                    return Ok(Vec::new());
                };
                item.slot
            }
        };
        DependencyEdge::recorded(&slot, id, near_kind, &self.name, natively_names)
            .map_err(|message| SourceError::Malformed { message })
    }

    fn configured_repository(&self) -> Result<&RepositoryTarget, SourceError> {
        self.repository
            .as_ref()
            .ok_or_else(|| SourceError::Refused {
                message: format!(
                    "source {} has no repository configured, and a GitHub Projects board has no \
                 repository of its own to create an issue in; set repository: owner/name on \
                 this source",
                    self.name
                ),
            })
    }

    /// The repository one new issue is created in, under the rule [`RepositoryTarget`]
    /// states.
    ///
    /// The fallback is demanded first, whichever arm answers: a write without a configured
    /// repository is refused naming the field exactly as it was before the rule existed,
    /// so a source that could not write before cannot write now, rather than writing for
    /// the one item whose own field happens to decide it.
    ///
    /// Everything this refuses is refused before `createIssue`, so a refusal leaves no
    /// issue behind: an entry that is not a repository on [`RepositoryTarget::HOST`], an
    /// entry owned by someone other than the owner of the parent issue's repository —
    /// GitHub accepts a sub-issue from another repository of the same owner and from no
    /// other, so `addSubIssue` would refuse it after the issue existed — a parent the
    /// board does not hold, and a parent that is a draft, which GitHub gives no sub-issues,
    /// both of which `addSubIssue` would likewise refuse too late. Whether the entry exists
    /// and is visible to the token is checked where its node id is resolved, still before
    /// `createIssue`. The parent is read by its own id through [`Self::item_by_id`] — never
    /// looked up in a listing of the board, which can be minutes behind an issue its own
    /// `projectItems` already places on it — and that read answers first from this process's
    /// own record, so a project created moments ago in this command answers though GitHub
    /// has not caught up.
    async fn creation_target(
        &self,
        incoming: &Incoming<'_>,
    ) -> Result<RepositoryTarget, SourceError> {
        let fallback = self.configured_repository()?;
        let what = |incoming: &Incoming<'_>| {
            format!(
                "{} {:?}",
                incoming.written.kind().describes(),
                incoming.title
            )
        };
        let parent = match incoming.parent {
            Some(parent) => Some(self.item_by_id(parent).await?.ok_or_else(|| {
                SourceError::Refused {
                    message: format!(
                        "GitHub project issue {} was not found on the board of source {}, so {} \
                         cannot be filed under it",
                        parent.0,
                        self.name,
                        what(incoming)
                    ),
                }
            })?),
            None => None,
        };
        let parents_repository = parent
            .as_ref()
            .map(|parent| {
                // A draft is on the board and so is found, but it has no repository to
                // place a task in and GitHub gives it no sub-issues, so `addSubIssue`
                // would refuse the task only once `createIssue` had made it.
                if parent.content_kind == ContentKind::DraftIssue {
                    return Err(SourceError::Refused {
                        message: format!(
                            "GitHub project item {} on the board of source {} is a draft, \
                             which cannot have sub-issues, so {} cannot be filed under it",
                            parent.id.0,
                            self.name,
                            what(incoming)
                        ),
                    });
                }
                // An issue's repository is where a sub-issue is placed and whose owner it
                // is compared against, so a parent whose repository this source cannot
                // spell as `owner/name` — GitHub's login grammar is wider than this
                // source's floor — is one nothing can be filed under.
                parent
                    .own_repository
                    .as_ref()
                    .and_then(|origin| RepositoryTarget::from_origin(origin).ok())
                    .ok_or_else(|| SourceError::Malformed {
                        message: format!(
                            "GitHub project issue {} on the board of source {} is in {}, which \
                             is not a {}/owner/name repository this source can place {} in",
                            parent.id.0,
                            self.name,
                            parent
                                .own_repository
                                .as_ref()
                                .map_or("no repository", Repository::as_str),
                            RepositoryTarget::HOST,
                            what(incoming)
                        ),
                    })
            })
            .transpose()?;
        match incoming.repositories {
            [named] => {
                let target =
                    RepositoryTarget::from_origin(named).map_err(|_| SourceError::Refused {
                        message: format!(
                            "{} names repository {}, which is not a {}/owner/name repository \
                             source {} can create an issue in; name one that is, or name none",
                            what(incoming),
                            named.as_str(),
                            RepositoryTarget::HOST,
                            self.name
                        ),
                    })?;
                if let Some(parents) = &parents_repository
                    && parents.owner != target.owner
                {
                    return Err(SourceError::Refused {
                        message: format!(
                            "{} names repository {}, owned by {}, but its project's issue is in \
                             {}, owned by {}, and GitHub files a sub-issue only in a repository \
                             of the same owner as its parent issue; name a repository of {}, or \
                             name none",
                            what(incoming),
                            target.slug(),
                            target.owner,
                            parents.slug(),
                            parents.owner,
                            parents.owner
                        ),
                    });
                }
                Ok(target)
            }
            _ => Ok(parents_repository.unwrap_or_else(|| fallback.clone())),
        }
    }

    /// The node id of the repository `incoming` is being created in, or the refusal naming
    /// the item and the repository the token cannot see.
    ///
    /// Resolved once per command per repository; see [`Self::repository_cache`].
    async fn repository_id(
        &self,
        repository: &RepositoryTarget,
        incoming: &Incoming<'_>,
    ) -> Result<String, SourceError> {
        if let Some(id) = self.repository_cache()?.get(repository).cloned() {
            return Ok(id);
        }
        let data = self
            .graphql(
                graphql::REPOSITORY,
                json!({"owner":repository.owner,"name":repository.name}),
            )
            .await?;
        let node = data
            .get("repository")
            .filter(|value| !value.is_null())
            .ok_or_else(|| SourceError::Refused {
                message: format!(
                    "GitHub repository {} was not found or is not visible to the token, so {} \
                     {:?} cannot be created in it",
                    repository.slug(),
                    incoming.written.kind().describes(),
                    incoming.title
                ),
            })?;
        let id = required_str(node, "id")?.to_owned();
        self.repository_cache()?
            .insert(repository.clone(), id.clone());
        Ok(id)
    }

    fn repository_cache(
        &self,
    ) -> Result<std::sync::MutexGuard<'_, BTreeMap<RepositoryTarget, String>>, SourceError> {
        self.repository_cache
            .lock()
            .map_err(|_| SourceError::Unavailable {
                message: "this source's record of the destination repository was left \
                          inconsistent by an earlier failure; next: run the command again"
                    .into(),
            })
    }

    /// Create or update one board item, whichever kind it is.
    async fn write_item(
        &self,
        incoming: &Incoming<'_>,
        target: Option<&NativeId>,
        depends_on: &[DependencyEdge],
    ) -> Result<NativeId, SourceError> {
        // Refused before anything is read or written: a task or a project titled the way
        // this board spells a document would land as an issue this same source reads back
        // as a document, so the field this destination cannot carry is named rather than
        // written and silently reclassified.
        if let Written::Work(kind, _) = incoming.written
            && incoming.title.starts_with(DESIGN_TITLE_PREFIX)
        {
            return Err(SourceError::Refused {
                message: format!(
                    "the title of this {} begins {DESIGN_TITLE_PREFIX:?}, which is how source {} \
                     spells a document, so it would read back as one rather than as a {}; \
                     retitle it, or copy it as a document",
                    kind.marker(),
                    self.name,
                    kind.marker()
                ),
            });
        }
        // The destination is read by its own id, and whether this board holds it is decided
        // by that read — its own `projectItems` — rather than by whether a listing of the
        // board happens to include it yet. See the module documentation.
        let existing = match target {
            Some(target) => {
                Some(
                    self.item_by_id(target)
                        .await?
                        .ok_or_else(|| SourceError::Refused {
                            message: format!("GitHub destination item {} was not found", target.0),
                        })?,
                )
            }
            None => None,
        };
        let existing = existing.as_ref();
        let board = self
            .fields_for(existing, incoming.written.status().is_some())
            .await?;
        let status_target = incoming
            .written
            .status()
            .map(|status| self.resolved_target(status.category))
            .transpose()?;
        let column = match (incoming.written.status(), status_target.as_ref()) {
            (Some(status), Some(target)) => self.column_for(&board.fields, status, target)?,
            _ => None,
        };
        let content_kind = existing.map_or(ContentKind::Issue, |item| item.content_kind);
        if content_kind == ContentKind::DraftIssue {
            if let (Some(StatusTarget::Terminal(_, _)), Some(status)) =
                (status_target.as_ref(), incoming.written.status())
            {
                return Err(self.closes_a_draft(status.category));
            }
            if incoming.parent.is_some() {
                return Err(SourceError::Refused {
                    message: "GitHub draft items cannot be a project's sub-issue".into(),
                });
            }
        }
        match existing {
            Some(item) if content_kind == ContentKind::Issue => {
                if item.labels != incoming.labels {
                    return Err(SourceError::Refused {
                        message: "GitHub issue labels differ from the labels being written".into(),
                    });
                }
            }
            _ => {
                if !incoming.labels.is_empty() {
                    return Err(SourceError::Refused {
                        message: "GitHub items created by this destination carry no labels".into(),
                    });
                }
            }
        }

        // An existing issue is never moved; a new one is created where the rule says. The
        // repository the issue really lives in is what the slot below is written against,
        // so a single entry that is where the issue is created travels as no key at all,
        // and the read side derives it back from the issue.
        let (own_repository, creation_target) = match existing {
            Some(item) => (item.own_repository.clone(), None),
            None => {
                let target = self.creation_target(incoming).await?;
                let origin = Repository::try_from(target.origin())
                    .map_err(|message| SourceError::Config { message })?;
                (Some(origin), Some(target))
            }
        };
        let (native, fallback) = self
            .partition_edges(incoming.written.kind(), content_kind, depends_on)
            .await?;
        let slot = slot_metadata(incoming, own_repository.as_ref(), &fallback);
        let body = compose_body(incoming.content, &slot)?;
        // Read before anything is created, for the reason the field below is: a value
        // this destination cannot store has to refuse, and refusing after `createIssue`
        // would leave an issue behind that nothing asked for. The engine writes a
        // qualified id here; a caller handing this key anything else is told so rather
        // than having it silently stored as no origin at all.
        // llmlint: ignore[boundary_inputs_validated, changed_behavior_has_e2e] The qualified id's syntax is the engine's and not this plugin's to police: `GlobalId` is deliberately absent from the contract crate because a plugin never sees a qualified id (AGENTS.md), no plugin crate may depend on the engine to parse one, and `docs/metadata.md` says the contents of this key are what no plugin constructs or interprets. What this boundary owns is whether the value is a string its text field can hold, and that is what it checks.
        let origin = match incoming.metadata.get(ORIGIN_KEY) {
            None => "",
            Some(Value::String(origin)) => origin.as_str(),
            Some(other) => {
                return Err(SourceError::Refused {
                    message: format!(
                        "{ORIGIN_KEY} holds a qualified id spelled as a string, and this item's \
                         is {other}"
                    ),
                });
            }
        };
        // Resolved before anything is created: a board that cannot carry the copy origin
        // has to refuse the write, and refusing it after `createIssue` would leave an
        // issue behind that nothing asked for.
        let origin_field = match Board::field(&board.fields, ORIGIN_FIELD)? {
            Some(field) => {
                if required_str(field, "__typename")? != "ProjectV2Field" {
                    return Err(SourceError::Refused {
                        message: format!(
                            "GitHub board source-owned {ORIGIN_FIELD} field is not a text field"
                        ),
                    });
                }
                Some(required_str(field, "id")?.to_owned())
            }
            None if incoming.metadata.contains_key(ORIGIN_KEY) => {
                return Err(SourceError::Refused {
                    message: format!(
                        "GitHub board has no source-owned {ORIGIN_FIELD} text field, and the \
                         item carries {ORIGIN_KEY}; add a text field named {ORIGIN_FIELD} to \
                         the board"
                    ),
                });
            }
            None => None,
        };

        let Landed {
            content_id,
            item_id,
            url,
            number,
        } = match existing {
            Some(item) => {
                self.update_existing(item, incoming, &body, status_target.as_ref())
                    .await?;
                Landed {
                    content_id: item.id.clone(),
                    item_id: item.item_id.clone(),
                    url: item.url.clone(),
                    number: item.number,
                }
            }
            None => {
                let target = creation_target
                    .as_ref()
                    .ok_or_else(|| SourceError::Malformed {
                        message: "a new item was decided without a repository to create it in"
                            .into(),
                    })?;
                self.create_and_file_issue(board.id.as_str(), target, incoming, &body)
                    .await?
            }
        };

        let written_option = column.as_ref().map(|(_, _, name)| name.clone());
        let column = column.map(|(field, option, _)| (field, option));
        // Creating an item here is several calls — `createIssue`, `addProjectV2ItemById`,
        // then each board field, the parent and the dependencies — and GitHub can fail at
        // any of them. Everything this source can refuse *before* the first of those is
        // already checked above, so what is left is GitHub itself failing part way. When it
        // does over an item this call created, the issue is taken back: a write that
        // refused must not leave an item behind that nobody asked for, and one that does
        // makes the retry create a second.
        let landed = self
            .finish_write(
                board.id.as_str(),
                incoming,
                &content_id,
                &item_id,
                content_kind,
                existing,
                origin_field.as_deref(),
                origin,
                column,
                status_target.as_ref(),
                &native,
            )
            .await;
        if let Err(error) = landed {
            if existing.is_none() {
                // Best effort, and the write's own failure is what the caller is told: a
                // refusal naming the tidy-up would hide why the write failed at all.
                let _ = self.delete_issue(&content_id).await;
            }
            return Err(error);
        }

        let written_status = match (incoming.written.status(), status_target.as_ref()) {
            (Some(_), Some(StatusTarget::Terminal(_, reason))) => {
                self.statuses
                    .status(written_option.as_deref(), true, Some(reason.reason()))
            }
            (Some(_), Some(StatusTarget::Column(_))) => {
                self.statuses.status(written_option.as_deref(), false, None)
            }
            (Some(status), _) => status.clone(),
            (None, _) => Status {
                category: StatusCategory::Unknown,
                name: "Open".to_owned(),
            },
        };

        // So the rest of this command reads what it just did rather than what the board
        // said before it. See `remember_written` for which half takes it.
        let remembered = Resolved {
            item_id,
            id: content_id.clone(),
            content_kind,
            kind: incoming.written.kind(),
            title: incoming.title.to_owned(),
            // The visible half of the body this write composed, split back off it the
            // way a read splits it — so what this record reports is what a read of the
            // same issue reports, rather than the person's text with the metadata slot
            // still on the end of it.
            body: metadata_body(body.clone())?.0,
            raw_body: body.clone(),
            // A document has no status of its own; what it reads back as is whatever
            // the issue's own state says, which is what a re-read reports.
            status: written_status,
            option: written_option.or_else(|| existing.and_then(|item| item.option.clone())),
            // What `state_input` asked for: closed for a terminal target, open for any other
            // status, and the issue's own state left as it was by a document write.
            closed: content_kind == ContentKind::Issue
                && match status_target.as_ref() {
                    Some(StatusTarget::Terminal(_, _)) => true,
                    Some(_) => false,
                    None => existing.is_some_and(|item| item.closed),
                },
            delivers: incoming.delivers.to_vec(),
            delivered_by: incoming.delivered_by.to_vec(),
            labels: incoming.labels.to_vec(),
            parent: incoming.parent.cloned(),
            origin: (!origin.is_empty()).then(|| origin.to_owned()),
            number,
            // In the update path this is the item's own url, read off `existing` where the
            // record above was bound, so one expression serves both halves.
            url,
            created_at: existing.and_then(|item| item.created_at),
            updated_at: existing.and_then(|item| item.updated_at),
            own_repository,
            repositories: incoming.repositories.to_vec(),
            slot,
            board_id: Some(board.id.as_str().to_owned()),
            fields: board
                .fields
                .get("nodes")
                .and_then(Value::as_array)
                .cloned()
                .unwrap_or_default(),
        };
        self.remember_written(remembered, existing.is_none())?;
        Ok(content_id)
    }

    /// Everything a write does after the item exists: its board fields, its parent, and
    /// its dependencies.
    ///
    /// Split out of `write_item` so there is one place a failure past the point of no
    /// return is caught, rather than a tidy-up repeated at each `?` above.
    // llmlint: ignore[suppressions_justified] This is the tail of `write_item` lifted out
    // so there is one place a failure past the point of no return is caught, and its
    // arguments are exactly the values that tail already had in scope. Bundling them into a
    // struct would describe no concept — it would be "the arguments of this function" — and
    // would put the whole of `write_item`'s locals behind one more indirection.
    #[allow(clippy::too_many_arguments)]
    async fn finish_write(
        &self,
        board_id: &str,
        incoming: &Incoming<'_>,
        content_id: &NativeId,
        item_id: &str,
        content_kind: ContentKind,
        existing: Option<&Resolved>,
        origin_field: Option<&str>,
        origin: &str,
        column: Option<(String, String)>,
        status_target: Option<&StatusTarget>,
        native: &[String],
    ) -> Result<(), SourceError> {
        if let Some(field_id) = origin_field {
            self.set_item_field(board_id, item_id, field_id, json!({"text":origin}))
                .await?;
        }

        if let Some((field_id, option_id)) = column {
            self.set_item_field(
                board_id,
                item_id,
                &field_id,
                json!({"singleSelectOptionId":option_id}),
            )
            .await?;
        }

        if content_kind == ContentKind::Issue
            && matches!(status_target, Some(StatusTarget::Terminal(_, _)))
        {
            self.update_content(
                ContentKind::Issue,
                content_id,
                json!({"stateInput":state_input(status_target)}),
            )
            .await?;
        }

        if content_kind == ContentKind::Issue {
            self.reparent(
                existing.and_then(|item| item.parent.clone()),
                content_id,
                incoming.parent,
            )
            .await?;
            // A document takes part in no dependency graph, so writing one neither reads
            // nor changes the issue's own `blockedBy` relationships. Reconciling them
            // against the empty list a document write carries would *delete* whatever
            // relationships a person had made on that issue, which is a write nobody
            // asked for.
            if incoming.written.kind() != BoardKind::Document {
                self.reconcile_blocked_by(content_id, native).await?;
            }
        }
        Ok(())
    }

    /// Delete one issue, which takes its board item with it.
    async fn delete_issue(&self, id: &NativeId) -> Result<(), SourceError> {
        let data = self
            .graphql(graphql::DELETE_ISSUE, json!({"input":{"issueId":id.0}}))
            .await?;
        data.pointer("/deleteIssue/repository")
            .filter(|value| !value.is_null())
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub issue deletion returned no repository".into(),
            })?;
        self.forget(id)?;
        Ok(())
    }

    /// Remove one item this copy created, so a copy that could not finish leaves the board
    /// as it found it.
    ///
    /// Deleting the issue takes its board item with it, so there is no second mutation to
    /// keep in step. An id the board does not hold is not an error: the item is already
    /// gone, which is the state this asks for. Which that is, is decided by reading the item
    /// by its own id — a listing of the board can still be missing an item it holds, and
    /// reading that as *already gone* would leave behind the very item this was asked to
    /// take back.
    async fn delete_item(&self, id: &NativeId) -> Result<(), SourceError> {
        let Some(item) = self.item_by_id(id).await? else {
            return Ok(());
        };
        if item.content_kind == ContentKind::DraftIssue {
            return Err(SourceError::Refused {
                message: format!(
                    "GitHub item {} is a draft, and this source removes an item by deleting \
                     its issue; next: remove it from the board by hand",
                    id.0
                ),
            });
        }
        let data = self
            .graphql(graphql::DELETE_ISSUE, json!({"input":{"issueId":id.0}}))
            .await?;
        data.pointer("/deleteIssue/repository")
            .filter(|value| !value.is_null())
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub issue deletion returned no repository".into(),
            })?;
        self.forget(id)?;
        Ok(())
    }

    /// The issue a comment call on `task` is about, or `None` when this board holds no such
    /// task.
    ///
    /// Resolved exactly as [`TaskSource::get_task`] resolves it, so the comment verbs and a
    /// read of the task cannot disagree about which ids name one: a project or a document of
    /// this board is not a task here either.
    ///
    /// A **draft** is a task with nowhere to keep a comment, because GitHub keeps comments on
    /// issues and a draft is not one. It is refused rather than answered with an empty page,
    /// which would read as a task nobody has commented on yet.
    async fn commented_issue(&self, task: &NativeId) -> Result<Option<NativeId>, SourceError> {
        let Some(item) = self
            .item_by_id(task)
            .await?
            .filter(|item| item.kind == BoardKind::Work(ItemKind::Task))
        else {
            return Ok(None);
        };
        if item.content_kind == ContentKind::DraftIssue {
            return Err(SourceError::Refused {
                message: format!(
                    "task {} of source {} is a draft item on the board, and GitHub keeps \
                     comments on issues alone, so a draft has none to read or write; next: \
                     convert the draft to an issue on the board, then comment on the issue it \
                     becomes",
                    task.0, self.name
                ),
            });
        }
        Ok(Some(item.id))
    }

    /// Whether the comment `comment` is one of `issue`'s own.
    ///
    /// Read before an edit or a removal is sent, because GitHub's comment mutations take the
    /// comment's id and nothing else: a comment id given against the wrong task would
    /// otherwise change a comment on some other issue entirely. An id that names nothing, or
    /// names something that is not an issue comment, is a comment this task does not have —
    /// which is what GitHub refusing to resolve it means too.
    async fn comment_is_on(
        &self,
        issue: &NativeId,
        comment: &NativeId,
    ) -> Result<bool, SourceError> {
        let asked = self
            .graphql(graphql::COMMENT_ISSUE, json!({"id":comment.0}))
            .await;
        let data = match asked {
            Ok(data) => data,
            Err(error) if unresolvable_node(&error) => return Ok(false),
            Err(error) => return Err(error),
        };
        let Some(node) = data.get("node").filter(|value| !value.is_null()) else {
            return Ok(false);
        };
        if optional_str(node, "__typename")? != Some("IssueComment") {
            return Ok(false);
        }
        let on = node.get("issue").ok_or_else(|| SourceError::Malformed {
            message: format!("GitHub issue comment {} names no issue", comment.0),
        })?;
        Ok(required_str(on, "id")? == issue.0)
    }

    /// Which far ends this item's own `blockedBy` relationship holds, and which it cannot.
    async fn partition_edges(
        &self,
        near_kind: BoardKind,
        near_content: ContentKind,
        depends_on: &[DependencyEdge],
    ) -> Result<(Vec<String>, Vec<DependencyEdge>), SourceError> {
        let mut native = Vec::new();
        let mut fallback = Vec::new();
        for edge in depends_on {
            let same_source = edge
                .to
                .source()
                .is_none_or(|source| source == self.name.as_str());
            // A qualified id's source segment runs to its *first* colon — `GlobalId` and
            // `DependencyEndpoint::source` both read it that way — and a native id may hold
            // colons of its own, so the far end is everything after that one separator.
            // Splitting at the last would truncate `work:urn:task:7` to `7`.
            let far_id = if edge.to.is_qualified() {
                edge.to
                    .id()
                    .split_once(':')
                    .map_or(edge.to.id(), |(_, native)| native)
            } else {
                edge.to.id()
            };
            // A same-source far end is read by its own id, exactly as the item it is a far end
            // of is: whether this board holds it is that read's answer, never a listing's.
            let far = if same_source {
                Some(
                    self.item_by_id(&NativeId(far_id.to_owned()))
                        .await?
                        .ok_or_else(|| SourceError::Refused {
                            message: format!("GitHub dependency item {far_id} was not found"),
                        })?,
                )
            } else {
                None
            };
            let far = far.as_ref();
            // The caller says which kind the far end is, and this board holds the far end
            // itself, so a disagreement is settled here rather than stored: recorded, the
            // wrong kind would read back as a cross-level edge that never existed; written
            // natively, it would name a relationship of a different level than the caller
            // asked for.
            //
            // A far end this board holds as a *document* fails the same comparison and is
            // refused by the same sentence: `ItemKind` has no document variant because
            // nothing may point at one, so no caller can name it correctly and the refusal
            // is the only honest answer.
            if let Some(disagreeing) = far.filter(|far| far.kind != BoardKind::Work(edge.to.kind)) {
                return Err(SourceError::Refused {
                    message: format!(
                        "GitHub dependency item {far_id} is a {} of this board, and this item \
                         names it as a {}; record the kind it is",
                        disagreeing.kind.describes(),
                        edge.to.kind.marker()
                    ),
                });
            }
            // A draft has neither `blockedBy` nor `blocking`, so no edge of one is native
            // however the far end is spelled — and one classified native here would be
            // written nowhere at all, because a draft's native reconciliation never runs.
            let native_here = near_content == ContentKind::Issue
                && far.is_some_and(|far| {
                    far.content_kind == ContentKind::Issue
                        && BoardKind::Work(edge.to.kind) == near_kind
                });
            if native_here {
                native.push(far_id.to_owned());
            } else {
                fallback.push(edge.clone());
            }
        }
        Ok((native, fallback))
    }

    async fn update_existing(
        &self,
        item: &Resolved,
        incoming: &Incoming<'_>,
        body: &Option<String>,
        status_target: Option<&StatusTarget>,
    ) -> Result<(), SourceError> {
        let title = incoming.written_title();
        let mut fields = match item.content_kind {
            ContentKind::DraftIssue => json!({"title":title,"body":body}),
            ContentKind::Issue => json!({"title":title,"body":body,
                                         "stateInput":state_input(status_target)}),
        };
        if matches!(status_target, Some(StatusTarget::Terminal(_, _))) {
            fields
                .as_object_mut()
                .expect("update fields are an object")
                .remove("stateInput");
        }
        self.update_content(item.content_kind, &item.id, fields)
            .await
    }

    /// Update one board item's content with exactly `fields` beside its id, through the
    /// mutation its kind takes: `updateIssue` for an issue, `updateProjectV2DraftIssue` for
    /// a draft.
    ///
    /// Every input field either mutation leaves out is a field GitHub leaves as it is, which
    /// is what lets a narrow write carry the one thing it changes and nothing else.
    async fn update_content(
        &self,
        kind: ContentKind,
        id: &NativeId,
        fields: Value,
    ) -> Result<(), SourceError> {
        let (operation, id_key, pointer) = match kind {
            ContentKind::DraftIssue => (
                graphql::UPDATE_DRAFT,
                "draftIssueId",
                "/updateProjectV2DraftIssue/draftIssue",
            ),
            ContentKind::Issue => (graphql::UPDATE_ISSUE, "id", "/updateIssue/issue"),
        };
        let mut input = fields;
        input[id_key] = json!(id.0);
        let data = self.graphql(operation, json!({"input":input})).await?;
        let returned = data
            .pointer(pointer)
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub item update returned no item".into(),
            })?;
        if required_str(returned, "id")? != id.0 {
            return Err(SourceError::Malformed {
                message: "GitHub item update returned the wrong item".into(),
            });
        }
        Ok(())
    }

    /// Creates one issue, files it on the board, and reports what a read of it would say:
    /// its content id, its board item id, and the web address GitHub gave it.
    ///
    /// Two calls rather than one: `createIssue` needs a repository and answers with an
    /// issue that is on no board, and `addProjectV2ItemById` is what puts it there. A
    /// terminal status is not written here: `finish_write` selects its option first and
    /// closes the issue after, so a close never lands on an item whose board cannot show it.
    ///
    /// The address and the number come back here because this is the only place either is
    /// known before GitHub's own board read catches up — an item this run created answers
    /// the reads that follow it out of the record below, and one remembered without them
    /// would report no location and no key for the rest of the run.
    async fn create_and_file_issue(
        &self,
        board_id: &str,
        repository: &RepositoryTarget,
        incoming: &Incoming<'_>,
        body: &Option<String>,
    ) -> Result<Landed, SourceError> {
        let repository_id = self.repository_id(repository, incoming).await?;
        let data = self
            .graphql(
                graphql::CREATE_ISSUE,
                json!({"input":{
                    "repositoryId":repository_id,"title":incoming.written_title(),"body":body
                }}),
            )
            .await?;
        let created = data
            .pointer("/createIssue/issue")
            .filter(|value| !value.is_null())
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub issue creation returned no issue".into(),
            })?;
        let content_id = NativeId(required_str(created, "id")?.to_owned());
        // Optional although GitHub's schema makes it non-null: the issue exists by now, so
        // a response without it is not worth failing a landed write over — the item simply
        // reports no location until the board read catches up, which is what it did before.
        let url = optional_str(created, "url")?.map(str::to_owned);
        // The issue exists from here on, so an unreadable number and a refused board
        // filing below each try, best effort, to take it back: an issue in the repository
        // that is on no board is an item nobody asked for and nothing here would find again.
        //
        // Its number is optional on the same terms its address is — a landed write is not
        // worth failing over a member that came back missing, and such an item reports no
        // handle until a board read catches up. A number that is *present* and is not an
        // unsigned integer is still a response this source cannot read.
        let number = match created_issue_number(created) {
            Ok(number) => number,
            Err(error) => {
                let _ = self.delete_issue(&content_id).await;
                return Err(error);
            }
        };
        let added = match self
            .graphql(
                graphql::ADD_TO_BOARD,
                json!({"input":{"projectId":board_id,"contentId":content_id.0}}),
            )
            .await
        {
            Ok(added) => added,
            Err(error) => {
                let _ = self.delete_issue(&content_id).await;
                return Err(error);
            }
        };
        let item = added
            .pointer("/addProjectV2ItemById/item")
            .filter(|value| !value.is_null())
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub board addition returned no project item".into(),
            })?;
        Ok(Landed {
            content_id,
            item_id: required_str(item, "id")?.to_owned(),
            url,
            number,
        })
    }

    /// Move one issue under the project it now belongs to, or out of the one it left.
    async fn reparent(
        &self,
        held: Option<NativeId>,
        child: &NativeId,
        wanted: Option<&NativeId>,
    ) -> Result<(), SourceError> {
        if held.as_ref() == wanted {
            return Ok(());
        }
        if let Some(held) = &held {
            self.sub_issue(graphql::REMOVE_SUB_ISSUE, held, child, "removeSubIssue")
                .await?;
        }
        if let Some(wanted) = wanted {
            self.sub_issue(graphql::ADD_SUB_ISSUE, wanted, child, "addSubIssue")
                .await?;
        }
        Ok(())
    }

    async fn sub_issue(
        &self,
        operation: &str,
        parent: &NativeId,
        child: &NativeId,
        root: &str,
    ) -> Result<(), SourceError> {
        let data = self
            .graphql(
                operation,
                json!({"input":{"issueId":parent.0,"subIssueId":child.0}}),
            )
            .await?;
        let issue =
            data.pointer(&format!("/{root}/issue"))
                .ok_or_else(|| SourceError::Malformed {
                    message: "GitHub sub-issue update returned no issue".into(),
                })?;
        let sub =
            data.pointer(&format!("/{root}/subIssue"))
                .ok_or_else(|| SourceError::Malformed {
                    message: "GitHub sub-issue update returned no sub-issue".into(),
                })?;
        if required_str(issue, "id")? != parent.0 || required_str(sub, "id")? != child.0 {
            return Err(SourceError::Malformed {
                message: "GitHub sub-issue update returned the wrong issues".into(),
            });
        }
        Ok(())
    }

    async fn reconcile_blocked_by(
        &self,
        content_id: &NativeId,
        native: &[String],
    ) -> Result<(), SourceError> {
        let current = self.native_dependency_ids(content_id).await?;
        for (operation, far_id) in current
            .iter()
            .filter(|id| !native.contains(id))
            .map(|id| (graphql::REMOVE_BLOCKED_BY, id))
            .chain(
                native
                    .iter()
                    .filter(|id| !current.contains(id))
                    .map(|id| (graphql::ADD_BLOCKED_BY, id)),
            )
        {
            let data = self
                .graphql(
                    operation,
                    json!({"input":{"issueId":content_id.0,"blockingIssueId":far_id}}),
                )
                .await?;
            let root = if operation == graphql::ADD_BLOCKED_BY {
                "addBlockedBy"
            } else {
                "removeBlockedBy"
            };
            let issue =
                data.pointer(&format!("/{root}/issue"))
                    .ok_or_else(|| SourceError::Malformed {
                        message: "GitHub dependency update returned no issue".into(),
                    })?;
            let blocker = data
                .pointer(&format!("/{root}/blockingIssue"))
                .ok_or_else(|| SourceError::Malformed {
                    message: "GitHub dependency update returned no blocking issue".into(),
                })?;
            if required_str(issue, "id")? != content_id.0 || required_str(blocker, "id")? != far_id
            {
                return Err(SourceError::Malformed {
                    message: "GitHub dependency update returned the wrong issues".into(),
                });
            }
        }
        Ok(())
    }
}

/// What resolving one node id reached; see [`GitHubProjectsSource::reach`].
enum Reached {
    /// An issue this board holds, resolved into everything this source reports about it.
    Held(Box<Resolved>),
    /// Nothing this board holds: no such node, or a node on some other board.
    Nothing,
    /// A board draft, which [`graphql::ISSUE`] reaches and reads nothing of, so it is read
    /// again by [`GitHubProjectsSource::draft_by_id`].
    Draft,
}

/// What GitHub says when a string is not a node id it can resolve.
///
/// Matched because it is the ordinary answer to a project selector naming a project by its
/// *name*, and reporting that as a failure would make naming one impossible. It is read
/// off the refusal GitHub sent, never guessed from the shape of the string: this source
/// does not define the syntax of a GitHub node id and would be wrong about it.
const UNRESOLVABLE_NODE: &str = "could not resolve to a node";

/// Whether this refusal is GitHub saying the id names no node at all.
fn unresolvable_node(error: &SourceError) -> bool {
    matches!(error, SourceError::Refused { message }
        if message.to_ascii_lowercase().contains(UNRESOLVABLE_NODE))
}

/// One project name, as a search qualifier which filters on it at the server.
///
/// Quoted so the whole title is one phrase rather than a bag of words, with the two
/// characters GitHub's own quoting grammar gives a meaning inside a quoted phrase escaped
/// the way it documents. A title matched here is still compared for equality afterwards:
/// the qualifier narrows what the server sends, and this source decides what it names.
fn title_qualifier(name: &str) -> String {
    let escaped = name.replace('\\', "\\\\").replace('"', "\\\"");
    format!("in:title \"{escaped}\"")
}

/// The board, and every item on it this source reports.
#[derive(Clone)]
struct Board {
    id: String,
    fields: Value,
    items: Vec<Resolved>,
}

/// What a write needs of the board and nothing more: its node id and its field
/// definitions, in the shape a read of the board's own `fields` gives them.
///
/// Deliberately no items. A write decides which item it writes, which parent it files
/// under and which far ends it names by reading each of them by its own id; this is the
/// half of the board those reads cannot carry, and holding no item is what keeps it from
/// ever being asked whether an item is there.
#[derive(Clone)]
struct BoardFields {
    id: BoardId,
    fields: Value,
}

/// A board's node id: what a field write and `addProjectV2ItemById` address.
///
/// Never blank, because a blank one addresses no board — so an id GitHub answers blank is
/// refused where it is read, and one an item names blank is read as not named at all.
#[derive(Clone)]
struct BoardId(String);

/// Where one write left its item, for the record the rest of the command reads it out of.
///
/// A named record rather than a tuple because the update arm and the create arm each fill
/// all four, and two `Option`s of different meaning side by side in a tuple are two
/// positions a reader has to count.
struct Landed {
    /// The issue's own node id, which is the [`NativeId`] this source reports.
    content_id: NativeId,
    /// The board item's id, which is what a field write addresses.
    // llmlint: ignore[invalid_states_unrepresentable] This field and the one below are `Resolved::item_id` and `Resolved::url` carried out of one call: the update arm assigns them from an existing `Resolved` and the whole record is assigned straight back into one. A newtype introduced here alone would be wrapped at both of those boundaries and unwrapped at every use, and would make this private record disagree with the type the same values have on the struct they come from and return to. Where the board item id gets a newtype is on `Resolved`, which is the contract's own shape and not this change's to move.
    item_id: String,
    /// The web address GitHub gave the issue, when it gave one.
    // llmlint: ignore[invalid_states_unrepresentable] The answer `Resolved::url` and the contract's `Task::url` already record: a web address this source never parses, resolves or compares — it reads GitHub's string and hands it back, and `Location::Url` is where the contract gives it a shape. Validating it here would have this plugin decide what GitHub may call an address.
    url: Option<String>,
    /// The issue's number on its repository, when GitHub reported one.
    number: Option<u64>,
}

impl BoardId {
    fn parse(id: &str) -> Result<Self, SourceError> {
        if id.trim().is_empty() {
            return Err(SourceError::Malformed {
                message: "GitHub named a board with a blank node id".into(),
            });
        }
        Ok(Self(id.to_owned()))
    }

    fn as_str(&self) -> &str {
        &self.0
    }
}

impl Board {
    fn field<'a>(fields: &'a Value, name: &str) -> Result<Option<&'a Value>, SourceError> {
        complete_connection(fields, "project fields", NESTED_PAGE_SIZE)?;
        let nodes = fields
            .get("nodes")
            .and_then(Value::as_array)
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub project fields.nodes is not an array".into(),
            })?;
        Ok(nodes
            .iter()
            .find(|field| field.get("name").and_then(Value::as_str) == Some(name)))
    }
}

/// One board item, resolved into everything this source reports about it.
#[derive(Clone)]
struct Resolved {
    item_id: String,
    id: NativeId,
    content_kind: ContentKind,
    kind: BoardKind,
    title: String,
    body: Option<String>,
    /// The body exactly as GitHub holds it, metadata slot and all, which is what a write
    /// that changes the slot alone has to keep byte for byte outside it.
    raw_body: Option<String>,
    status: Status,
    /// The name of the board `Status` option this item sits in, as the board spells it.
    option: Option<String>,
    /// Whether this item's issue is closed. A draft has no such state and is never closed.
    closed: bool,
    /// The tasks this one delivers, read out of its slot. Empty for anything not a task.
    delivers: Vec<TaskRef>,
    /// Every task that delivers this one, read out of its slot. Empty for anything not a
    /// task.
    delivered_by: Vec<TaskRef>,
    labels: Vec<Label>,
    parent: Option<NativeId>,
    // llmlint: ignore[invalid_states_unrepresentable] The write side's reason, read back: this is the engine's qualified id, taken out of a board text field and handed on untouched. A newtype here would have this plugin define the syntax of an id `docs/metadata.md` says no plugin ever constructs or interprets.
    origin: Option<String>,
    /// The issue's own number on its repository, as GitHub reports it.
    ///
    /// `None` in exactly two cases: a draft, which has no number at all — `DraftIssue`
    /// declares none, and a draft is not filed in a repository to be numbered by one — and
    /// an issue this run created whose creating mutation answered without one, which is a
    /// response GitHub's own schema says cannot happen and which a landed write is not
    /// worth failing over. An `Issue` read off the board always has one.
    number: Option<u64>,
    url: Option<String>,
    created_at: Option<DateTime<Utc>>,
    updated_at: Option<DateTime<Utc>>,
    own_repository: Option<Repository>,
    repositories: Vec<Repository>,
    slot: BTreeMap<String, Value>,
    /// The node id of the board this item sits on, when the read that reached it said.
    board_id: Option<String>,
    /// The definition of every board field this item holds a value of, in the shape a read
    /// of the board's own `fields` gives one.
    ///
    /// Only the fields this item has a value in: a field it holds nothing of is not here,
    /// which says nothing about whether the board has it.
    fields: Vec<Value>,
}

impl Resolved {
    /// The board this item's own read names it on, when that read named one this source can
    /// address.
    fn named_board(&self) -> Option<BoardId> {
        self.board_id
            .as_deref()
            .and_then(|id| BoardId::parse(id).ok())
    }

    /// Whether this item holds a value of the board field called `name`, and so carries
    /// that field's definition. `false` says nothing about whether the board has the field.
    fn defines(&self, name: &str) -> bool {
        self.fields
            .iter()
            .any(|field| field.get("name").and_then(Value::as_str) == Some(name))
    }

    /// The metadata a caller sees: their own keys, plus the copy origin this source keeps
    /// in a field of its own, and none of the five keys that are only an encoding.
    ///
    /// The two delivery keys are left out for every kind, not only for a task: they are
    /// the encoding of [`Task::delivers`] and [`Task::delivered_by`], and a project or a
    /// document carrying one holds nothing a caller's own metadata could mean by it.
    fn metadata(&self) -> BTreeMap<String, Value> {
        let mut metadata = self.slot.clone();
        metadata.remove(Repository::METADATA_KEY);
        metadata.remove(DependencyEdge::RECORDED_KEY);
        metadata.remove(ItemKind::METADATA_KEY);
        metadata.remove(TaskRef::DELIVERS_KEY);
        metadata.remove(TaskRef::DELIVERED_BY_KEY);
        if let Some(origin) = &self.origin {
            metadata.insert(ORIGIN_KEY.to_owned(), Value::String(origin.clone()));
        }
        metadata
    }

    /// Where this item is, as a link a reader can open.
    ///
    /// A board is a hosted place and every issue on it has a web address, so that address
    /// is what "where is this?" means here — and [`Location::Url`] is what says which kind
    /// of place it is, so a reader knows to open it rather than to read a file out. It
    /// does not replace or derive from `url`: the field goes on reporting exactly what it
    /// reported before, and this says what that address *is*.
    ///
    /// An item GitHub gave no `url` for — a draft has none — reports no location at all
    /// rather than a third variant, which is the contract's "the source did not say". An
    /// issue this run created is not one of those: its address comes back from the
    /// creating mutation, so it is somewhere a reader can open from the moment it exists
    /// rather than from whenever the board read catches up.
    fn location(&self) -> Option<Location> {
        self.url.clone().map(Location::Url)
    }

    /// The short handle this board's backend shows people for a task: the issue's number
    /// alone, as a decimal string.
    ///
    /// The number alone rather than `owner/repo#1043`, because that is the contract's
    /// value for this backend. A draft has no number and so no handle, which is the
    /// contract's *absent* rather than a handle of some other shape — and the native
    /// [`Task::id`] here is the issue's GraphQL node id, which this neither replaces nor
    /// derives from.
    fn key(&self) -> Option<String> {
        self.number.map(|number| number.to_string())
    }

    fn task(&self) -> Task {
        Task {
            id: self.id.clone(),
            key: self.key(),
            title: self.title.clone(),
            content: self.body.clone(),
            status: self.status.clone(),
            labels: self.labels.clone(),
            project: self.parent.clone(),
            url: self.url.clone(),
            location: self.location(),
            created_at: self.created_at,
            updated_at: self.updated_at,
            metadata: self.metadata(),
            repositories: self.repositories.clone(),
            delivers: self.delivers.clone(),
            delivered_by: self.delivered_by.clone(),
        }
    }

    fn project(&self) -> Project {
        Project {
            id: self.id.clone(),
            title: self.title.clone(),
            content: self.body.clone(),
            status: self.status.clone(),
            labels: self.labels.clone(),
            url: self.url.clone(),
            location: self.location(),
            created_at: self.created_at,
            updated_at: self.updated_at,
            metadata: self.metadata(),
            repositories: self.repositories.clone(),
        }
    }

    /// The same issue as a document: the project it is filed under, and no status and no
    /// dependencies, because a document is not work.
    fn document(&self) -> Document {
        Document {
            id: self.id.clone(),
            title: self.title.clone(),
            content: self.body.clone(),
            project: self.parent.clone(),
            labels: self.labels.clone(),
            url: self.url.clone(),
            location: self.location(),
            created_at: self.created_at,
            updated_at: self.updated_at,
            metadata: self.metadata(),
            repositories: self.repositories.clone(),
        }
    }
}

/// What one write is, and the status that comes with being it.
///
/// One value rather than a [`BoardKind`] beside an `Option<Status>`: a document has no
/// status and a task or a project always has one, so "a document carrying a status" and
/// "a task carrying none" are states a write cannot be in rather than states every use
/// site below has to defend against.
enum Written<'a> {
    /// A document, which is not work and so has no status at all.
    Document,
    /// A task or a project, and the status it is being written with.
    Work(ItemKind, &'a Status),
}

impl Written<'_> {
    /// Which of the board's three kinds this write is.
    const fn kind(&self) -> BoardKind {
        match self {
            Self::Document => BoardKind::Document,
            Self::Work(kind, _) => BoardKind::Work(*kind),
        }
    }

    /// The status this write carries. A document carries none, so a write of one says
    /// nothing about the issue's open or closed state and selects no board `Status`
    /// option.
    const fn status(&self) -> Option<&Status> {
        match self {
            Self::Document => None,
            Self::Work(_, status) => Some(status),
        }
    }
}

/// The item being written, in the one shape all three write methods reach.
struct Incoming<'a> {
    written: Written<'a>,
    /// The title a person wrote. A document's goes onto the issue with
    /// [`DESIGN_TITLE_PREFIX`] put back, so a round trip returns the title that went in.
    title: &'a str,
    content: Option<&'a str>,
    labels: &'a [Label],
    metadata: &'a BTreeMap<String, Value>,
    repositories: &'a [Repository],
    parent: Option<&'a NativeId>,
    /// [`Task::delivers`], already checked. Empty for a project or a document, which is
    /// what keeps either key out of their slot.
    delivers: &'a [TaskRef],
    /// [`Task::delivered_by`], already checked. Empty for a project or a document.
    delivered_by: &'a [TaskRef],
}

impl Incoming<'_> {
    /// The title this write puts on the issue.
    fn written_title(&self) -> String {
        match self.written {
            Written::Document => format!("{DESIGN_TITLE_PREFIX}{}", self.title),
            Written::Work(..) => self.title.to_owned(),
        }
    }
}

#[derive(Clone, Copy, PartialEq, Eq)]
enum ContentKind {
    DraftIssue,
    Issue,
}

/// What one board issue is: a document, or the work an [`ItemKind`] names.
///
/// A type of this source's own rather than an `ItemKind` with a third variant, because
/// `ItemKind` names what a dependency endpoint points at and nothing may point at a
/// document — the contract keeps a document out of that enum deliberately. Holding the
/// board's three answers in one value is what makes every place that asks "which is this?"
/// answer all three, rather than a `document: bool` beside a `kind` that means nothing for
/// two thirds of the board.
#[derive(Clone, Copy, PartialEq, Eq)]
enum BoardKind {
    /// An issue whose title begins [`DESIGN_TITLE_PREFIX`].
    Document,
    /// Every other issue, and every draft.
    Work(ItemKind),
}

impl BoardKind {
    /// How a refusal names this kind to the person reading it.
    const fn describes(self) -> &'static str {
        match self {
            Self::Document => "document",
            Self::Work(kind) => kind.marker(),
        }
    }
}

/// Whether `labels` satisfies `filter`, matching by name, case-insensitively.
///
/// This is the local Markdown source's `labels_match`, spelled the same way on purpose:
/// the shared cross-source journeys assert one answer to one question, so two sources
/// that disagree about what "carries the label bug" means fail them.
fn labels_match(labels: &[Label], filter: &LabelFilter) -> bool {
    let holds = |name: &String| {
        labels
            .iter()
            .any(|label| label.name.eq_ignore_ascii_case(name))
    };
    (filter.any_of.is_empty() || filter.any_of.iter().any(holds))
        && filter.all_of.iter().all(holds)
        && !filter.none_of.iter().any(holds)
}

/// Whether `category` is one of `statuses`. An empty list is unfiltered rather than
/// "keeps nothing", which is what lets a `Vec<StatusCategory>` spell no filter at all.
fn status_matches(category: StatusCategory, statuses: &[StatusCategory]) -> bool {
    statuses.is_empty() || statuses.contains(&category)
}

/// Whether `title`/`content` satisfies `query`, matching case-insensitively.
///
/// `content` is the item's own prose — the body with this source's trailing metadata
/// comment already taken off — so a search never matches an encoding the author of the
/// issue never wrote.
fn text_matches(title: &str, content: Option<&str>, query: &TextQuery) -> bool {
    let terms = query.terms.to_lowercase();
    let in_title = title.to_lowercase().contains(&terms);
    let in_content = content.is_some_and(|body| body.to_lowercase().contains(&terms));
    match query.fields {
        TextFields::Title => in_title,
        TextFields::Content => in_content,
        TextFields::TitleOrContent => in_title || in_content,
    }
}

/// Whether `task` satisfies `query`, with `project` deciding the project predicate.
///
/// The project predicate is passed separately because a read narrowed to one project has
/// already answered it by asking *that project* for its own items — and re-applying it
/// there would compare the caller's selector, which may be a project's **name**, against
/// the id of the project that name resolved to, and keep nothing. Every other read passes
/// `query.project` and applies it here, which is what keeps `projects` a predicate this
/// source really does apply.
fn task_matches(task: &Task, query: &TaskQuery, project: &ProjectFilter) -> bool {
    labels_match(&task.labels, &query.labels)
        && status_matches(task.status.category, &query.statuses)
        && match project {
            ProjectFilter::Any => true,
            ProjectFilter::Orphans => task.project.is_none(),
            ProjectFilter::Is(id) => task.project.as_ref() == Some(id),
        }
        && query
            .text
            .as_ref()
            .is_none_or(|text| text_matches(&task.title, task.content.as_deref(), text))
}

fn project_matches(project: &Project, query: &ProjectQuery) -> bool {
    labels_match(&project.labels, &query.labels)
        && status_matches(project.status.category, &query.statuses)
        && query
            .text
            .as_ref()
            .is_none_or(|text| text_matches(&project.title, project.content.as_deref(), text))
}

/// The same three predicates a task query carries, minus the status filter.
///
/// A document is not work, so it has no status for one to compare against and the query
/// type carries none. The project predicate is the same one — a design issue filed under a
/// project issue is in that project, and one filed under nothing is in none — so it is
/// spelled the same way here rather than answered differently.
fn document_matches(document: &Document, query: &DocumentQuery, project: &ProjectFilter) -> bool {
    labels_match(&document.labels, &query.labels)
        && match project {
            ProjectFilter::Any => true,
            ProjectFilter::Orphans => document.project.is_none(),
            ProjectFilter::Is(id) => document.project.as_ref() == Some(id),
        }
        && query
            .text
            .as_ref()
            .is_none_or(|text| text_matches(&document.title, document.content.as_deref(), text))
}

#[async_trait::async_trait]
impl TaskSource for GitHubProjectsSource {
    fn kind(&self) -> &'static str {
        KIND
    }
    fn capabilities(&self) -> Capabilities {
        Capabilities {
            projects: Support::Native,
            documents: Support::Native,
            comments: Support::Native,
            orphan_tasks: Support::Native,
            filter_by_label: Support::Native,
            filter_by_status: Support::Native,
            search_title: Support::Native,
            search_content: Support::Native,
            task_dependencies: DependencySupport::BothDirections,
            project_dependencies: DependencySupport::BothDirections,
            max_page_size: MAX_PAGE_SIZE,
        }
    }
    async fn health(&self) -> Result<Health, SourceError> {
        let board = self.board_page(None, 1).await?;
        Ok(Health {
            reachable: true,
            detail: Some(format!(
                "reading GitHub project {}/{} ({})",
                self.owner,
                self.project_number,
                required_str(&board, "title")?
            )),
        })
    }
    async fn get_task(&self, id: &NativeId) -> Result<Option<Task>, SourceError> {
        Ok(self
            .item_by_id(id)
            .await?
            .filter(|item| item.kind == BoardKind::Work(ItemKind::Task))
            .map(|item| item.task()))
    }
    async fn get_project(&self, id: &NativeId) -> Result<Option<Project>, SourceError> {
        Ok(self
            .item_by_id(id)
            .await?
            .filter(|item| item.kind == BoardKind::Work(ItemKind::Project))
            .map(|item| item.project()))
    }
    async fn query_tasks(
        &self,
        query: &TaskQuery,
        page: &PageRequest,
    ) -> Result<Page<Task>, SourceError> {
        validate_page(page)?;
        // A read narrowed to one project asks that project for its own tasks, so nothing
        // about it costs what the rest of the board holds. Every other task read is a
        // question about the whole board and is answered by reading it.
        let (held, membership) = match &query.project {
            ProjectFilter::Is(project) => (
                self.project_children(project).await?,
                // Answered by where these items came from; see `task_matches`.
                &ProjectFilter::Any,
            ),
            ProjectFilter::Any | ProjectFilter::Orphans => {
                (self.board().await?.items, &query.project)
            }
        };
        // Filtered before paged: a page of a filtered result is a page of the survivors,
        // never the survivors of a page.
        let tasks = held
            .iter()
            .filter(|item| item.kind == BoardKind::Work(ItemKind::Task))
            .map(Resolved::task)
            .filter(|task| task_matches(task, query, membership))
            .collect();
        Ok(offset_page(
            tasks,
            numeric_cursor(page.cursor.as_ref())?,
            page.limit.min(MAX_PAGE_SIZE) as usize,
        ))
    }
    async fn query_projects(
        &self,
        query: &ProjectQuery,
        page: &PageRequest,
    ) -> Result<Page<Project>, SourceError> {
        validate_page(page)?;
        // The projects a board holds are found by an issue search scoped to that board,
        // never by walking the board's own item connection: what tells a project from a
        // task is the `parent` each issue carries, which costs nothing to read.
        let projects = self
            .board_issues()
            .await?
            .iter()
            .filter(|item| item.kind == BoardKind::Work(ItemKind::Project))
            .map(Resolved::project)
            .filter(|project| project_matches(project, query))
            .collect();
        Ok(offset_page(
            projects,
            numeric_cursor(page.cursor.as_ref())?,
            page.limit.min(MAX_PAGE_SIZE) as usize,
        ))
    }
    async fn get_document(&self, id: &NativeId) -> Result<Option<Document>, SourceError> {
        Ok(self
            .item_by_id(id)
            .await?
            .filter(|item| item.kind == BoardKind::Document)
            .map(|item| item.document()))
    }
    async fn query_documents(
        &self,
        query: &DocumentQuery,
        page: &PageRequest,
    ) -> Result<Page<Document>, SourceError> {
        validate_page(page)?;
        // Narrowed to one project, this is the same sub-issue read a task list scoped to
        // that project makes — a document filed under a project is a sub-issue of it too,
        // and which of them come back is the kind this caller asked for.
        let (held, membership) = match &query.project {
            ProjectFilter::Is(project) => (
                self.project_children(project).await?,
                // Answered by where these items came from; see `task_matches`.
                &ProjectFilter::Any,
            ),
            ProjectFilter::Any | ProjectFilter::Orphans => {
                (self.board().await?.items, &query.project)
            }
        };
        // Filtered before paged, exactly as a task read is: a page of a filtered result is
        // a page of the survivors, never the survivors of a page.
        let documents = held
            .iter()
            .filter(|item| item.kind == BoardKind::Document)
            .map(Resolved::document)
            .filter(|document| document_matches(document, query, membership))
            .collect();
        Ok(offset_page(
            documents,
            numeric_cursor(page.cursor.as_ref())?,
            page.limit.min(MAX_PAGE_SIZE) as usize,
        ))
    }
    async fn labels(&self, page: &PageRequest) -> Result<Page<Label>, SourceError> {
        validate_page(page)?;
        let offset = numeric_cursor(page.cursor.as_ref())?;
        let mut labels = self
            .board()
            .await?
            .items
            .into_iter()
            .flat_map(|item| item.labels)
            .fold(Vec::new(), |mut all, label| {
                if !all.iter().any(|x: &Label| x.id == label.id) {
                    all.push(label);
                }
                all
            });
        labels.sort_by(|a, b| a.name.cmp(&b.name).then(a.id.0.cmp(&b.id.0)));
        Ok(offset_page(
            labels,
            offset,
            page.limit.min(MAX_PAGE_SIZE) as usize,
        ))
    }
    async fn task_dependencies(
        &self,
        id: &NativeId,
        direction: Direction,
        page: &PageRequest,
    ) -> Result<Page<DependencyEdge>, SourceError> {
        self.dependencies(id, ItemKind::Task, direction, page).await
    }
    async fn project_dependencies(
        &self,
        id: &NativeId,
        direction: Direction,
        page: &PageRequest,
    ) -> Result<Page<DependencyEdge>, SourceError> {
        self.dependencies(id, ItemKind::Project, direction, page)
            .await
    }

    fn writes(&self) -> WriteSupport {
        WriteSupport::Supported
    }

    /// Create or update one task.
    ///
    /// Its `delivers` and `delivered_by` are checked before anything is read or written —
    /// neither may name the task itself or name one task twice — and land in the body's
    /// metadata slot under their reserved keys, in place of any caller metadata of those
    /// names.
    async fn write_task(&self, write: &ItemWrite<Task>) -> Result<NativeId, SourceError> {
        let near = write.target.as_ref().unwrap_or(&write.item.id);
        for (key, entries) in [
            (TaskRef::DELIVERS_KEY, &write.item.delivers),
            (TaskRef::DELIVERED_BY_KEY, &write.item.delivered_by),
        ] {
            TaskRef::listed(key, near, Some(&self.name), entries.clone())
                .map_err(|message| SourceError::Refused { message })?;
        }
        self.write_item(
            &Incoming {
                written: Written::Work(ItemKind::Task, &write.item.status),
                title: &write.item.title,
                content: write.item.content.as_deref(),
                labels: &write.item.labels,
                metadata: &write.item.metadata,
                repositories: &write.item.repositories,
                parent: write.item.project.as_ref(),
                delivers: &write.item.delivers,
                delivered_by: &write.item.delivered_by,
            },
            write.target.as_ref(),
            &write.depends_on,
        )
        .await
    }

    async fn write_project(&self, write: &ItemWrite<Project>) -> Result<NativeId, SourceError> {
        self.write_item(
            &Incoming {
                written: Written::Work(ItemKind::Project, &write.item.status),
                title: &write.item.title,
                content: write.item.content.as_deref(),
                labels: &write.item.labels,
                metadata: &write.item.metadata,
                repositories: &write.item.repositories,
                parent: None,
                delivers: &[],
                delivered_by: &[],
            },
            write.target.as_ref(),
            &write.depends_on,
        )
        .await
    }

    /// Create or update one document, which is one issue titled the way this board spells
    /// a document.
    ///
    /// Everything else is exactly a task write: caller metadata goes to the same canonical
    /// JSON slot at the end of the body and comes back with its JSON types intact, a key
    /// or a field this board cannot carry is refused by name rather than dropped, a target
    /// naming an issue this board does not hold is refused rather than created, and an
    /// issue this call created is taken back when the rest of the write fails.
    async fn write_document(&self, write: &ItemWrite<Document>) -> Result<NativeId, SourceError> {
        // A document takes part in no dependency graph, so there is no far end to write
        // natively and none to record: a caller naming one is told so rather than having it
        // stored under the reserved key, where a later read would report an edge the
        // contract says cannot exist.
        if !write.depends_on.is_empty() {
            return Err(SourceError::Refused {
                message: format!(
                    "this write names {} dependencies for a document, and a document takes \
                     part in no dependency graph; next: put the dependency on the task or \
                     project the document is about",
                    write.depends_on.len()
                ),
            });
        }
        self.write_item(
            &Incoming {
                written: Written::Document,
                title: &write.item.title,
                content: write.item.content.as_deref(),
                labels: &write.item.labels,
                metadata: &write.item.metadata,
                repositories: &write.item.repositories,
                parent: write.item.project.as_ref(),
                delivers: &[],
                delivered_by: &[],
            },
            write.target.as_ref(),
            &[],
        )
        .await
    }

    /// Set one task's status alone.
    ///
    /// An open target reopens a closed issue with an `updateIssue` carrying only its
    /// `stateInput`, then selects the board option with `updateProjectV2ItemFieldValue`; a
    /// terminal target selects its mapped option, then closes with its fixed reason. No
    /// request carries a title, a body or a label. The status
    /// answered is what [`StatusMapping::status`] reads off the state just written, which is
    /// what a re-read reports.
    async fn set_task_status(
        &self,
        id: &NativeId,
        category: StatusCategory,
    ) -> Result<Option<Status>, SourceError> {
        self.set_status(id, category).await
    }

    /// Replace one task's `delivered_by` with a single body update that changes the
    /// metadata slot and nothing outside it.
    async fn set_delivered_by(
        &self,
        id: &NativeId,
        delivered_by: &[TaskRef],
    ) -> Result<Option<()>, SourceError> {
        self.replace_delivered_by(id, delivered_by).await
    }

    /// Set one key of one task issue's metadata with a single body update that changes the
    /// metadata slot and nothing outside it — no title, label, state or board field request —
    /// and sends nothing when the task already holds that value under the key.
    async fn set_task_metadata(
        &self,
        id: &NativeId,
        key: &MetadataKey,
        value: &Value,
    ) -> Result<Option<Task>, SourceError> {
        Ok(self
            .set_slot_key(id, BoardKind::Work(ItemKind::Task), key, value)
            .await?
            .map(|item| item.task()))
    }

    /// Set one key of one project issue's metadata, on exactly the terms of
    /// [`set_task_metadata`](TaskSource::set_task_metadata).
    async fn set_project_metadata(
        &self,
        id: &NativeId,
        key: &MetadataKey,
        value: &Value,
    ) -> Result<Option<Project>, SourceError> {
        Ok(self
            .set_slot_key(id, BoardKind::Work(ItemKind::Project), key, value)
            .await?
            .map(|item| item.project()))
    }

    /// Set one key of one design-document issue's metadata, on exactly the terms of
    /// [`set_task_metadata`](TaskSource::set_task_metadata).
    async fn set_document_metadata(
        &self,
        id: &NativeId,
        key: &MetadataKey,
        value: &Value,
    ) -> Result<Option<Document>, SourceError> {
        Ok(self
            .set_slot_key(id, BoardKind::Document, key, value)
            .await?
            .map(|item| item.document()))
    }

    async fn delete_task(&self, id: &NativeId) -> Result<(), SourceError> {
        self.delete_item(id).await
    }

    async fn delete_project(&self, id: &NativeId) -> Result<(), SourceError> {
        self.delete_item(id).await
    }

    async fn delete_document(&self, id: &NativeId) -> Result<(), SourceError> {
        self.delete_item(id).await
    }

    /// One page of the task issue's own comments, walked by GitHub's own cursor.
    ///
    /// Nothing here filters, so nothing has to be read ahead of the page: the caller's limit is
    /// the page GitHub is asked for and GitHub's `endCursor` is the cursor handed back.
    async fn task_comments(
        &self,
        task: &NativeId,
        page: &PageRequest,
    ) -> Result<Option<Page<Comment>>, SourceError> {
        validate_page(page)?;
        let Some(issue) = self.commented_issue(task).await? else {
            return Ok(None);
        };
        let after = page.cursor.as_ref().map(|cursor| cursor.0.as_str());
        let data = self
            .graphql(
                graphql::ISSUE_COMMENTS,
                json!({"id":issue.0,"first":page.limit.min(MAX_PAGE_SIZE),"after":after}),
            )
            .await?;
        // The issue was there a moment ago; one removed since is no longer a task here.
        let Some(node) = data.get("node").filter(|value| !value.is_null()) else {
            return Ok(None);
        };
        let connection = node
            .get("comments")
            .filter(|value| !value.is_null())
            .ok_or_else(|| SourceError::Malformed {
                message: format!(
                    "GitHub issue {} answered with no comments connection",
                    issue.0
                ),
            })?;
        let items = optional_nodes(Some(connection), "issue comments")?
            .into_iter()
            .flatten()
            .map(comment_from)
            .collect::<Result<Vec<_>, _>>()?;
        let next = next_cursor(connection)?;
        if let Some(next) = &next {
            validate_cursor_progress(after, &next.0)?;
        }
        Ok(Some(Page { items, next }))
    }

    /// Add one comment to the task's issue, as the account the token belongs to.
    ///
    /// The author is refused before anything is sent — not even the task is read — because
    /// no answer GitHub could give would make posting under another name than the one asked
    /// for the right outcome.
    async fn add_comment(
        &self,
        task: &NativeId,
        comment: &NewComment,
    ) -> Result<Option<Comment>, SourceError> {
        if let Some(author) = &comment.author {
            return Err(SourceError::Refused {
                message: format!(
                    "source {} cannot post a comment as {author:?}: GitHub records the account \
                     the token signs in as the author of every comment; next: leave --author \
                     out, and the comment is posted as that account",
                    self.name
                ),
            });
        }
        let Some(issue) = self.commented_issue(task).await? else {
            return Ok(None);
        };
        let data = self
            .graphql(
                graphql::ADD_COMMENT,
                json!({"input":{"subjectId":issue.0,"body":comment.body.as_str()}}),
            )
            .await?;
        let subject = data
            .pointer("/addComment/subject")
            .filter(|value| !value.is_null())
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub comment addition returned no subject".into(),
            })?;
        if required_str(subject, "id")? != issue.0 {
            return Err(SourceError::Malformed {
                message: "GitHub comment addition answered about another issue".into(),
            });
        }
        let added = data
            .pointer("/addComment/commentEdge/node")
            .filter(|value| !value.is_null())
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub comment addition returned no comment".into(),
            })?;
        comment_from(added).map(Some)
    }

    async fn edit_comment(
        &self,
        task: &NativeId,
        comment: &NativeId,
        body: &CommentBody,
    ) -> Result<Option<Comment>, SourceError> {
        let Some(issue) = self.commented_issue(task).await? else {
            return Ok(None);
        };
        if !self.comment_is_on(&issue, comment).await? {
            return Ok(None);
        }
        let data = self
            .graphql(
                graphql::UPDATE_COMMENT,
                json!({"input":{"id":comment.0,"body":body.as_str()}}),
            )
            .await?;
        let edited = data
            .pointer("/updateIssueComment/issueComment")
            .filter(|value| !value.is_null())
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub comment update returned no comment".into(),
            })?;
        let edited = comment_from(edited)?;
        if edited.id != *comment {
            return Err(SourceError::Malformed {
                message: "GitHub comment update returned the wrong comment".into(),
            });
        }
        Ok(Some(edited))
    }

    async fn delete_comment(
        &self,
        task: &NativeId,
        comment: &NativeId,
    ) -> Result<Option<NativeId>, SourceError> {
        let Some(issue) = self.commented_issue(task).await? else {
            return Ok(None);
        };
        if !self.comment_is_on(&issue, comment).await? {
            return Ok(None);
        }
        let data = self
            .graphql(graphql::DELETE_COMMENT, json!({"input":{"id":comment.0}}))
            .await?;
        // The payload says nothing about the comment it removed, so what is checked is that
        // GitHub answered the mutation at all rather than leaving it unanswered.
        data.get("deleteIssueComment")
            .filter(|value| !value.is_null())
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub comment deletion returned no payload".into(),
            })?;
        Ok(Some(comment.clone()))
    }

    /// Every request this source has recorded, and what each of GitHub's two budgets was
    /// attributed — read off the same accounting the session report is rendered from, so
    /// the two cannot count one request two ways.
    async fn metering(&self) -> Result<Option<Metering>, SourceError> {
        Ok(Some(self.ledger.snapshot().metering()))
    }
}

/// One issue comment as the contract carries it.
///
/// `author` is absent both when GitHub answers `null` for an account that no longer exists
/// and when it answers an actor with no login, because either way the source did not say who
/// wrote it — which is what an absent author means, rather than an author called nothing.
fn comment_from(value: &Value) -> Result<Comment, SourceError> {
    Ok(Comment {
        id: NativeId(required_str(value, "id")?.to_owned()),
        author: optional_str(value.get("author").unwrap_or(&Value::Null), "login")?
            .map(str::to_owned),
        created_at: optional_time(value, "createdAt")?,
        updated_at: optional_time(value, "updatedAt")?,
        body: required_str(value, "body")?.to_owned(),
        url: optional_str(value, "url")?.map(str::to_owned),
    })
}

/// Where the recorded tail of a dependency walk resumes; see
/// [`GitHubProjectsSource::recorded_edges`].
const RECORDED_CURSOR: &str = "onetaskgraph.depends_on:";

/// The board text field this source keeps a copy's origin in.
///
/// Named after the key it holds, and held to that name by the guard below rather than by
/// a reader noticing.
const ORIGIN_FIELD: &str = "onetaskgraph.origin";

/// The metadata key that field holds.
///
/// The engine owns this key and spells it once as `GlobalId::ORIGIN_KEY`; a plugin never
/// constructs or interprets the qualified id it carries. This source names it only to
/// route it — a short, typed value belongs in a typed field rather than in the body slot
/// a caller's own prose shares.
///
/// Restated rather than imported, because no plugin crate may depend on the engine. What
/// keeps the two spellings one contract is `scripts/check-origin-key-spelling.sh`, a
/// target in `check`: it reads the engine's own literal and fails naming the file and the
/// line when a plugin's parts from it either way. Drift here has one symptom — a copy
/// that creates a second item every run instead of finding the one it wrote — and that is
/// too late to learn it.
const ORIGIN_KEY: &str = "onetaskgraph.origin";

/// Where a recorded tail resumes, refusing a cursor no walk in `direction` reported.
///
/// The reserved key holds forward edges and nothing else — the reverse of a recorded edge
/// is derived from the far end, never written down on the near item — so only a forward
/// walk ever reports one of these cursors. A reverse read carrying one is resuming a walk
/// it did not come from, and it is told so rather than answered with an empty page that
/// reads as a walk which ended.
fn recorded_offset(
    cursor: Option<&str>,
    direction: Direction,
) -> Result<Option<usize>, SourceError> {
    cursor
        .and_then(|cursor| cursor.strip_prefix(RECORDED_CURSOR))
        .map(|offset| {
            if direction != Direction::DependsOn {
                return Err(SourceError::Config {
                    message: format!(
                        "{RECORDED_CURSOR}{offset} resumes recorded forward edges, which a \
                         reverse dependency read never issues; resume it in the direction \
                         that reported it"
                    ),
                });
            }
            offset.parse().map_err(|_| SourceError::Config {
                message: format!("{RECORDED_CURSOR}{offset} is not a recorded-edge cursor"),
            })
        })
        .transpose()
}

fn recorded_page(edges: Vec<DependencyEdge>, offset: usize, limit: usize) -> Page<DependencyEdge> {
    let mut page = offset_page(edges, offset, limit.max(1));
    page.next = page
        .next
        .map(|cursor| Cursor(format!("{RECORDED_CURSOR}{}", cursor.0)));
    page
}

/// The kind of one issue reached through a dependency connection.
///
/// The same questions the board scan asks, over the fields the dependency document
/// selects, and in the same order: the design prefix first, then a sub-issue is a task,
/// then anything with sub-issues or the marker is a project.
///
/// # Errors
///
/// A far end this board holds as a document is refused rather than reported. The two
/// answers that are not refusals would both be wrong: reporting it as a task names an id
/// no task read of this source can find, and reporting it as a project names one no
/// project read can. There is no third value to return — `ItemKind` has no document
/// variant, because nothing may point at a document — so the relationship itself is what
/// the person is told about.
fn related_kind(value: &Value) -> Result<ItemKind, SourceError> {
    let id = required_str(value, "id")?;
    if required_str(value, "title")?.starts_with(DESIGN_TITLE_PREFIX) {
        return Err(SourceError::Refused {
            message: format!(
                "GitHub issue {id} is a document of this board — its title begins \
                 {DESIGN_TITLE_PREFIX:?} — and nothing may depend on a document or be depended \
                 on by one; next: remove that issue's blocking relationship on this board"
            ),
        });
    }
    let parent = optional_str(value.get("parent").unwrap_or(&Value::Null), "id")?;
    if parent.is_some() {
        return Ok(ItemKind::Task);
    }
    let (_, slot) = metadata_body(optional_str(value, "body")?.map(str::to_owned))?;
    let marked = ItemKind::from_metadata(&slot).map_err(|message| SourceError::Malformed {
        message: format!("GitHub issue {id}: {message}"),
    })?;
    let sub_issues = sub_issue_total(value)?;
    Ok(if sub_issues > 0 || marked == Some(ItemKind::Project) {
        ItemKind::Project
    } else {
        ItemKind::Task
    })
}

/// The `IssueStateUpdateInput` one status target asks for.
///
/// `stateInput` and `state` are mutually exclusive on `UpdateIssueInput`, and only this
/// one is ever sent. A non-terminal status always asks for `OPEN`, which is what reopens
/// a currently-closed issue: without that the item would read back `Unknown` and a copy
/// would report a change forever. A document has no status at all, and asks for neither.
fn state_input(target: Option<&StatusTarget>) -> Value {
    match target {
        Some(StatusTarget::Terminal(_, reason)) => {
            json!({"value":"CLOSED","stateReason":reason.reason()})
        }
        Some(StatusTarget::Column(_) | StatusTarget::Disabled) => json!({"value":"OPEN"}),
        // A document has no status, so a write of one says nothing about the issue's open
        // or closed state rather than forcing it open: `stateInput` is what carries that
        // instruction, and an explicit null asks for no change to it.
        None => Value::Null,
    }
}

/// The metadata one write stores in the item's body slot.
///
/// The typed fields travel as themselves, so the three reserved keys are rebuilt here
/// rather than carried: the kind marker so an empty project stays readable, the
/// repository list only when it is not exactly the issue's own repository, and the far
/// ends no relationship here can name.
fn slot_metadata(
    incoming: &Incoming<'_>,
    own_repository: Option<&Repository>,
    fallback: &[DependencyEdge],
) -> BTreeMap<String, Value> {
    let mut metadata = incoming.metadata.clone();
    metadata.remove(ORIGIN_KEY);
    match incoming.written.kind() {
        BoardKind::Work(kind) => metadata.insert(
            ItemKind::METADATA_KEY.to_owned(),
            Value::String(kind.marker().to_owned()),
        ),
        // A document is told by its title, so it carries no kind marker: that key names
        // what a dependency endpoint points at, and nothing may point at a document.
        BoardKind::Document => metadata.remove(ItemKind::METADATA_KEY),
    };
    let derivable = own_repository
        .map(|own| incoming.repositories == [own.clone()])
        .unwrap_or(incoming.repositories.is_empty());
    if derivable {
        metadata.remove(Repository::METADATA_KEY);
    } else {
        metadata.insert(
            Repository::METADATA_KEY.to_owned(),
            Value::Array(
                incoming
                    .repositories
                    .iter()
                    .map(|repository| Value::String(repository.as_str().to_owned()))
                    .collect(),
            ),
        );
    }
    // The typed lists are what land, whatever the caller's own metadata held under their
    // keys: a key of either name travelling beside the field would otherwise be a second
    // answer to the same question, and the field is the one the contract names.
    for (key, entries) in [
        (TaskRef::DELIVERS_KEY, incoming.delivers),
        (TaskRef::DELIVERED_BY_KEY, incoming.delivered_by),
    ] {
        set_task_list(&mut metadata, key, entries);
    }
    if fallback.is_empty() {
        metadata.remove(DependencyEdge::RECORDED_KEY);
    } else {
        metadata.insert(
            DependencyEdge::RECORDED_KEY.to_owned(),
            Value::Array(
                fallback
                    .iter()
                    .map(|edge| json!({"id":edge.to.id(),"kind":edge.to.kind}))
                    .collect(),
            ),
        );
    }
    metadata
}

/// Every label one item carries, from its content's own connection and nowhere else.
///
/// There is no second place to read one from: no document this source sends selects the
/// board's built-in `Labels` field, because GitHub derives it from the content and a draft
/// cannot carry one at all. The module documentation records the three schema facts that
/// settle it.
fn labels(content: &Value) -> Result<Vec<Label>, SourceError> {
    optional_nodes(content.get("labels"), "content labels")?
        .into_iter()
        .flatten()
        .map(|v| {
            Ok(Label {
                id: NativeId(required_str(v, "id")?.to_owned()),
                name: required_str(v, "name")?.to_owned(),
                color: optional_str(v, "color")?.map(str::to_owned),
            })
        })
        .collect()
}

/// The definition of each board field one item's values are values of, in the shape a read
/// of the board's own `fields` gives one.
///
/// A value names its field through a fragment on that field's own type, so the type is
/// known from which kind of value it is: a single-select value's field is a
/// `ProjectV2SingleSelectField`, options and all, and a text value's is a `ProjectV2Field`.
/// A value whose field carried no id, or an empty one, says nothing usable and is left out.
fn field_definitions(field_values: &[Value]) -> Vec<Value> {
    field_values
        .iter()
        .filter_map(|value| {
            let field = value.get("field")?.as_object()?;
            field.get("id")?.as_str().filter(|id| !id.is_empty())?;
            let typename = if value.get("text").is_some() {
                "ProjectV2Field"
            } else if value.get("name").is_some() {
                "ProjectV2SingleSelectField"
            } else {
                return None;
            };
            let mut defined = field.clone();
            defined.insert("__typename".to_owned(), json!(typename));
            Some(Value::Object(defined))
        })
        .collect()
}

fn text_field(field_values: &[Value], name: &str) -> Result<Option<String>, SourceError> {
    let Some(node) = field_values
        .iter()
        .find(|node| node.pointer("/field/name").and_then(Value::as_str) == Some(name))
    else {
        return Ok(None);
    };
    Ok(optional_str(node, "text")?.map(str::to_owned))
}

fn valid_github_owner(owner: &str) -> bool {
    !owner.is_empty()
        && owner.len() <= 39
        && !owner.starts_with('-')
        && !owner.ends_with('-')
        && !owner.contains("--")
        && owner
            .bytes()
            .all(|byte| byte.is_ascii_alphanumeric() || byte == b'-')
}

/// GitHub's repository-name grammar: 1-100 ASCII letters, digits, `-`, `_` or `.`, and
/// neither of the two names a path segment already means.
fn valid_github_repository_name(name: &str) -> bool {
    !name.is_empty()
        && name.len() <= 100
        && name != "."
        && name != ".."
        && name
            .bytes()
            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.'))
}

fn valid_environment_name(name: &str) -> bool {
    let mut bytes = name.bytes();
    bytes
        .next()
        .is_some_and(|byte| byte.is_ascii_alphabetic() || byte == b'_')
        && bytes.all(|byte| byte.is_ascii_alphanumeric() || byte == b'_')
}

/// How many sub-issues one issue has.
///
/// `Issue.subIssuesSummary` is `SubIssuesSummary!` and its `total` is `Int!`, so an
/// absent or non-integer one is a response this source cannot read — and reading it as
/// zero would classify a project as a task, which is exactly the mistake the marker
/// exists to keep from happening quietly.
fn sub_issue_total(issue: &Value) -> Result<u64, SourceError> {
    let summary = issue
        .get("subIssuesSummary")
        .ok_or_else(|| SourceError::Malformed {
            message: "GitHub issue is missing subIssuesSummary".into(),
        })?;
    summary
        .get("total")
        .and_then(Value::as_u64)
        .ok_or_else(|| SourceError::Malformed {
            message: "GitHub issue subIssuesSummary.total is not an unsigned integer".into(),
        })
}

/// One issue's own `number`.
///
/// An issue always has one: GitHub declares `Issue.number` as `Int!` and every selection of
/// an issue in this module asks for it. So a read of one that comes back without it, or
/// with something that is not an unsigned integer, is a response this source cannot read —
/// absence here is **not** "this issue has no number". A draft is the content that has
/// none, and a draft never reaches this: the caller decides on `__typename` first, the way
/// it does for `subIssuesSummary`, which `DraftIssue` equally declares nothing for.
fn issue_number(issue: &Value) -> Result<u64, SourceError> {
    issue
        .get("number")
        .and_then(Value::as_u64)
        .ok_or_else(|| SourceError::Malformed {
            message: "GitHub issue number is missing or is not an unsigned integer".into(),
        })
}

/// The `number` a creating mutation answered with, and `None` when it answered without one;
/// why a missing one is tolerated is at the call in `create_and_file_issue`.
fn created_issue_number(created: &Value) -> Result<Option<u64>, SourceError> {
    match created.get("number") {
        None | Some(Value::Null) => Ok(None),
        Some(value) => value
            .as_u64()
            .map(Some)
            .ok_or_else(|| SourceError::Malformed {
                message: "GitHub created issue number is not an unsigned integer".into(),
            }),
    }
}

fn required_str<'a>(value: &'a Value, field: &str) -> Result<&'a str, SourceError> {
    value
        .get(field)
        .and_then(Value::as_str)
        .ok_or_else(|| SourceError::Malformed {
            message: format!("GitHub response is missing string field {field}"),
        })
}

fn required_nonblank_str<'a>(value: &'a Value, field: &str) -> Result<&'a str, SourceError> {
    let found = required_str(value, field)?;
    if found.trim().is_empty() {
        return Err(SourceError::Malformed {
            message: format!("GitHub response has blank string field {field}"),
        });
    }
    Ok(found)
}

/// The slot's delimiters, which `docs/metadata.md` settles once for every source that
/// needs one — Linear spells them too, in its own description field.
///
/// Restated rather than shared, because a plugin crate depends on the contract crate and
/// nothing else of this workspace. `scripts/check-metadata-slot-encoding.sh`, a target in
/// `check`, is what keeps the two one encoding: drift is otherwise quiet, since each
/// source round-trips its own writes perfectly well under its own spelling.
const METADATA_OPEN: &str = "<!-- onetaskgraph.metadata\n";
const METADATA_CLOSE: &str = "\n-->";

/// What the composer puts between a non-empty visible body and the slot, and the one thing
/// the parser takes off the visible body when it takes the slot off — exactly once, so every
/// other trailing byte of the body comes back as it was written.
// llmlint: ignore[contracts_have_one_source_or_a_drift_gate] How a composer lays the slot after prose is this source's own; `docs/metadata.md` and its gate settle only the delimiters, and no other source declares a separator to reconcile against.
const METADATA_SEPARATOR: &str = "\n\n";

/// The visible body and the metadata slot at the end of it.
///
/// The encoding is the one `docs/metadata.md` settles for Linear, which is where its
/// reasons are. Only a comment at the very end is a slot; one in the middle is a person's
/// own content and is left alone. The visible body is everything before the slot less the
/// one [`METADATA_SEPARATOR`] the composer put there, byte for byte.
fn metadata_body(
    body: Option<String>,
) -> Result<(Option<String>, BTreeMap<String, Value>), SourceError> {
    let Some(body) = body else {
        return Ok((None, BTreeMap::new()));
    };
    let Some(slot) = slot_span(&body)? else {
        return Ok((Some(body), BTreeMap::new()));
    };
    let metadata =
        serde_json::from_str(&body[slot.encoded_start..slot.encoded_end]).map_err(|error| {
            SourceError::Malformed {
                message: format!(
                    "invalid canonical JSON in GitHub issue onetaskgraph metadata slot: {error}"
                ),
            }
        })?;
    let before = &body[..slot.start];
    let visible = before.strip_suffix(METADATA_SEPARATOR).unwrap_or(before);
    Ok(((!visible.is_empty()).then(|| visible.to_owned()), metadata))
}

/// Where the metadata slot sits in one body, as byte offsets into it.
struct SlotSpan {
    /// Where [`METADATA_OPEN`] begins.
    start: usize,
    /// Where the encoded JSON begins, just past [`METADATA_OPEN`].
    encoded_start: usize,
    /// Where the encoded JSON ends, at the start of [`METADATA_CLOSE`].
    encoded_end: usize,
    /// Just past [`METADATA_CLOSE`].
    end: usize,
}

/// The slot at the very end of `body`, or `None` when it has none.
///
/// The one reading of *where the slot is*, shared by [`metadata_body`], which reads it, and
/// [`with_slot`], which rewrites it — so the two cannot disagree about which comment is the
/// slot.
fn slot_span(body: &str) -> Result<Option<SlotSpan>, SourceError> {
    let Some(start) = body.rfind(METADATA_OPEN) else {
        return Ok(None);
    };
    let encoded_start = start + METADATA_OPEN.len();
    let Some(relative_end) = body[encoded_start..].find(METADATA_CLOSE) else {
        return Err(SourceError::Malformed {
            message: "unterminated onetaskgraph metadata slot in GitHub issue body".into(),
        });
    };
    let encoded_end = encoded_start + relative_end;
    let end = encoded_end + METADATA_CLOSE.len();
    if !body[end..].trim().is_empty() {
        return Ok(None);
    }
    Ok(Some(SlotSpan {
        start,
        encoded_start,
        encoded_end,
        end,
    }))
}

/// `body` with its metadata slot holding exactly `metadata`, and every byte outside the
/// slot as it was.
///
/// A slot that is there has its JSON replaced in place; one that becomes empty is removed
/// together with the one [`METADATA_SEPARATOR`] separating it from the prose before it. A
/// body with no slot gains one the way [`compose_body`] writes it — after that separator,
/// or alone in an empty body — and a body with no slot that is given no metadata is
/// returned as it is.
fn with_slot(body: &str, metadata: &BTreeMap<String, Value>) -> Result<String, SourceError> {
    let encoded = if metadata.is_empty() {
        None
    } else {
        Some(
            serde_json::to_string(metadata).map_err(|error| SourceError::Malformed {
                message: error.to_string(),
            })?,
        )
    };
    Ok(match (slot_span(body)?, encoded) {
        (Some(slot), Some(encoded)) => format!(
            "{}{encoded}{}",
            &body[..slot.encoded_start],
            &body[slot.encoded_end..]
        ),
        (Some(slot), None) => {
            let before = &body[..slot.start];
            format!(
                "{}{}",
                before.strip_suffix(METADATA_SEPARATOR).unwrap_or(before),
                &body[slot.end..]
            )
        }
        (None, None) => body.to_owned(),
        (None, Some(encoded)) if body.is_empty() => {
            format!("{METADATA_OPEN}{encoded}{METADATA_CLOSE}")
        }
        (None, Some(encoded)) => {
            format!("{body}{METADATA_SEPARATOR}{METADATA_OPEN}{encoded}{METADATA_CLOSE}")
        }
    })
}

/// Hold `entries` under `key` in one slot's metadata, or no such key when there are none.
fn set_task_list(metadata: &mut BTreeMap<String, Value>, key: &str, entries: &[TaskRef]) {
    if entries.is_empty() {
        metadata.remove(key);
    } else {
        metadata.insert(
            key.to_owned(),
            Value::Array(
                entries
                    .iter()
                    .map(|entry| Value::String(entry.as_str().to_owned()))
                    .collect(),
            ),
        );
    }
}

fn compose_body(
    content: Option<&str>,
    metadata: &BTreeMap<String, Value>,
) -> Result<Option<String>, SourceError> {
    let visible = content.unwrap_or_default();
    if metadata.is_empty() {
        return Ok((!visible.is_empty()).then(|| visible.to_owned()));
    }
    let encoded = serde_json::to_string(metadata).map_err(|error| SourceError::Malformed {
        message: error.to_string(),
    })?;
    Ok(Some(if visible.is_empty() {
        format!("{METADATA_OPEN}{encoded}{METADATA_CLOSE}")
    } else {
        format!("{visible}{METADATA_SEPARATOR}{METADATA_OPEN}{encoded}{METADATA_CLOSE}")
    }))
}

fn required_bool(value: &Value, field: &str) -> Result<bool, SourceError> {
    value
        .get(field)
        .and_then(Value::as_bool)
        .ok_or_else(|| SourceError::Malformed {
            message: format!("GitHub response is missing boolean field {field}"),
        })
}
fn optional_str<'a>(value: &'a Value, field: &str) -> Result<Option<&'a str>, SourceError> {
    match value.get(field) {
        None | Some(Value::Null) => Ok(None),
        Some(value) => value
            .as_str()
            .map(Some)
            .ok_or_else(|| SourceError::Malformed {
                message: format!("GitHub response field {field} is not a string or null"),
            }),
    }
}
fn optional_nodes<'a>(
    connection: Option<&'a Value>,
    name: &str,
) -> Result<Option<&'a Vec<Value>>, SourceError> {
    match connection {
        None | Some(Value::Null) => Ok(None),
        Some(value) => value
            .get("nodes")
            .and_then(Value::as_array)
            .map(Some)
            .ok_or_else(|| SourceError::Malformed {
                message: format!("GitHub {name}.nodes is not an array"),
            }),
    }
}
fn complete_connection(connection: &Value, name: &str, size: u32) -> Result<(), SourceError> {
    let page_info = connection
        .get("pageInfo")
        .ok_or_else(|| SourceError::Malformed {
            message: format!("GitHub {name} has no pageInfo"),
        })?;
    if required_bool(page_info, "hasNextPage")? {
        return Err(SourceError::Malformed {
            message: format!(
                "GitHub {name} exceeds the supported nested connection size of {size}"
            ),
        });
    }
    Ok(())
}
fn optional_time(value: &Value, field: &str) -> Result<Option<DateTime<Utc>>, SourceError> {
    optional_str(value, field)?
        .map(|timestamp| {
            timestamp.parse().map_err(|error| SourceError::Malformed {
                message: format!("GitHub response field {field} is not a timestamp: {error}"),
            })
        })
        .transpose()
}
fn validate_page(page: &PageRequest) -> Result<(), SourceError> {
    if page.limit == 0 {
        Err(SourceError::Config {
            message: "page limit must be at least 1".into(),
        })
    } else {
        Ok(())
    }
}
fn next_cursor(connection: &Value) -> Result<Option<Cursor>, SourceError> {
    let page = connection
        .get("pageInfo")
        .filter(|value| value.is_object())
        .ok_or_else(|| SourceError::Malformed {
            message: "GitHub connection is missing pageInfo".into(),
        })?;
    if required_bool(page, "hasNextPage")? {
        let cursor = required_str(page, "endCursor")?;
        validate_cursor_progress(None, cursor)?;
        Ok(Some(Cursor(cursor.into())))
    } else {
        Ok(None)
    }
}
fn validate_cursor_progress(previous: Option<&str>, next: &str) -> Result<(), SourceError> {
    if next.is_empty() || previous == Some(next) {
        Err(SourceError::Malformed {
            message: "GitHub pagination cursor is empty or did not advance".into(),
        })
    } else {
        Ok(())
    }
}
fn numeric_cursor(cursor: Option<&Cursor>) -> Result<usize, SourceError> {
    cursor.map_or(Ok(0), |c| {
        c.0.parse().map_err(|_| SourceError::Config {
            message: "page cursor is invalid".into(),
        })
    })
}
fn offset_page<T>(mut items: Vec<T>, offset: usize, limit: usize) -> Page<T> {
    if offset > items.len() {
        return Page::last(vec![]);
    }
    let tail = items.split_off(offset);
    let mut selected = tail;
    let next = (selected.len() > limit).then(|| Cursor((offset + limit).to_string()));
    selected.truncate(limit);
    Page {
        items: selected,
        next,
    }
}