feat(forge): merge-queue provider with Trunk and a queue sweep (RIG-5183)

[rigel-mintaka]

Summary

Status board T15 (RIG-5183): a modular queue provider interface, with Trunk as the first provider. Its state is stored on the PR and kept current by a sweep.

• forge.MergeQueue (Name, Entries) and forge.Trunk over POST /v1/getSubmittedPullRequests, at most 50 PRs per call. Request and response shapes follow Trunk's public OpenAPI reference, "Get several submitted pull requests from a merge queue".
• State mapping:
  • not_ready and pending map to queued.
  • testing and tests_passed map to testing.
  • failed and pending_failure map to failed.
  • cancelled maps to removed, and merged to merged.
  • A queued or testing entry with isCurrentlySubmittedToQueue: false maps to removed.
  • A PR listed in notFound is absent.
• PullRequestHydrator.Hydrate sets PullRequest.merge_queue after GetPullRequest. A queue error is logged and never fails the hydrate. A repo with no configured queue makes no Trunk call.
• MergeQueueSweeper.Run runs on the serve errgroup. Every 2 minutes it reads the open PRs of each configured repo, writes pr.mergeQueue with jsonb_set only when the value differs, and republishes linked issues only on a change.
• Config:
  • --forge-merge-queues / COMPASS_FORGE_MERGE_QUEUES (owner/name=trunk:branch, comma-separated) sets forge_repo_subscriptions.merge_queue and merge_queue_branch at boot and clears repos that are not listed.
  • --forge-trunk-token-secret names a declared server-only secret.
  • The sweeper is built only when at least one repo is configured.

Deviations from the record

• ingest.QueueConfigs gains MergeQueueRepos(ctx) and MergeQueueHost(), so the sweep enumerates repos from the same stored config the hydrator reads.
• Store.OpenPullRequests takes the forge host.
• MergeQueueSink.PublishPullRequestMergeQueue takes an observedAt. Queue writes are ordered by when the provider was asked (pull_requests.merge_queue_observed_at), so a slow sweep can neither clear a newer entry nor restore an older one. PR upserts never write mergeQueue.
• Queue config does not create subscriptions. A configured repo must already be watched.

Tests

• TestTrunkEntriesMapsStatesAndRequest and TestTrunkEntriesMapsCancelledSubmissionToRemoved cover the state table, including removed and absent. Mutating the removal condition fails the test.
• TestPullRequestHydratorMergeQueue: a queue error leaves the hydrate green, and an unconfigured repo makes no Trunk call.
• TestMergeQueueSweeperPublishesConfiguredEntries, TestMergeQueueSweeperClearsMissingEntries.
• pgtests:
  • TestSetPullRequestMergeQueueChangesOnlyOnDifferentEntry
  • TestPublishPullRequestMergeQueueUpdatesLinkedIssueOnlyWhenChanged
  • TestServeMergeQueueSweeperPersistsChangedEntryWithinOneTick: a running Serve with a fake Trunk persists a changed entry.
• Flag parsing: TestValidateMergeQueueConfigs, TestResolveForgeMapping.

Stacked on #2194 (T14).

[linear-code]

RIG-5183

[github-actions]

Compass engineering docs preview: https://compass-forge-rig-5183-merge.compass-eng-docs.pages.dev

Deployed from compass-forge/rig-5183-merge-queue at 37a9f7f.

Changed pages:

• docs/self-host.md

[rigel-mintaka]

Review status at head 37a9f7f2: clean. The first review pass had six medium findings (terminal failed state, missing/null churn, queue-only enrolment, token on redirects and response bodies in logs, recurring-sweep test, self-host docs); all are fixed in 15a53c9d. The follow-up high finding (a stale clear or entry could win a race) is fixed in 37a9f7f2 by an observation watermark, and its re-review is clean. Two lows were dismissed with reasons: unknown Trunk states fail closed, and production paths never hydrate disabled repos.