From 8e0bd63727217e64e18be7b6fad244d4aedf3c39 Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Wed, 28 Oct 2026 10:32:44 -0400 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=90=9B=20fix:=20claim=20release=20re-?= =?UTF-8?q?derives=20040=20from=20the=20claim=20ledger;=20close-on-merge?= =?UTF-8?q?=20on=20the=20webhook;=20ledger=20backfill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A claim release on an issue whose covering PR the duplicate-PR claim ledger already held re-derived 010-actionable because enrichCoveringPR only trusted the store's memory of a 040 record. Nine issues on the hosted spoke sat at 010 with bucket=claimed_by_pr for hours while webhook-driven cached cycles skipped the reconcile sweeps. - enrichCoveringPR falls back to the ledger (SetPRClaimLookup) for claims FilterClaimedIssues would suppress (IssueClaim.CoversOpenIssue), after the existing liveness read; cmd/hive wires it with the red+stale valve. - A MERGED pull_request delivery runs the close-on-merge ledger sweep for that PR at once (CloseOnMergeOptions.OnlyPR*), independent of the reconcile pass cadence. - BackfillCoveredByLedger reconciles store records below 040 under an open ledger claim on every eval cycle, cached ones included. Signed-off-by: Andrew Anderson --- ...xed-claim-release-rederives-covering-pr.md | 1 + src/cmd/hive/close_on_merge_sweep.go | 32 ++- src/cmd/hive/eval_cycle_source.go | 2 +- src/cmd/hive/github_client_config.go | 4 + src/cmd/hive/main.go | 24 ++ src/cmd/hive/webhook_pr_claims.go | 65 ++++- src/cmd/hive/webhook_pr_claims_test.go | 35 ++- src/pkg/github/client.go | 5 + src/pkg/github/close_on_merge.go | 28 +- src/pkg/github/close_on_merge_forge_test.go | 37 +++ src/pkg/github/prclaims.go | 12 + src/pkg/github/stage_facts_sink.go | 56 +++- src/pkg/github/stage_ledger_backfill.go | 131 +++++++++ src/pkg/github/stage_ledger_backfill_test.go | 264 ++++++++++++++++++ 14 files changed, 671 insertions(+), 25 deletions(-) create mode 100644 changelog.d/fixed-claim-release-rederives-covering-pr.md create mode 100644 src/pkg/github/stage_ledger_backfill.go create mode 100644 src/pkg/github/stage_ledger_backfill_test.go diff --git a/changelog.d/fixed-claim-release-rederives-covering-pr.md b/changelog.d/fixed-claim-release-rederives-covering-pr.md new file mode 100644 index 0000000000..1a6bbcbc8b --- /dev/null +++ b/changelog.d/fixed-claim-release-rederives-covering-pr.md @@ -0,0 +1 @@ +- Issue stage records no longer regress to `010-actionable` on a claim release while the duplicate-PR claim ledger holds an open PR that covers the issue: the out-of-cycle stage facts consult the ledger (not only the store's memory) and re-derive `040-covered-by-pr`; a merged `pull_request` webhook now runs close-on-merge for that PR's issues at once instead of waiting for the next reconcile pass; and every eval cycle (cached ones included) backfills store records that sit below 040 under an open ledger claim, so the scanner stops being re-offered issues an open PR already fixes. diff --git a/src/cmd/hive/close_on_merge_sweep.go b/src/cmd/hive/close_on_merge_sweep.go index 56039ed47d..0ddeded022 100644 --- a/src/cmd/hive/close_on_merge_sweep.go +++ b/src/cmd/hive/close_on_merge_sweep.go @@ -96,6 +96,23 @@ func (s *closeOnMergeScheduler) mode(client *github.Client) github.APIBudgetMode return fn(client) } +// closeOnMergeOptionsFor is the policy both the scheduled sweep and the +// webhook-triggered one (closeOnMergeForDelivery) close issues under. +func closeOnMergeOptionsFor(cfg *config.Config, logger *slog.Logger, now func() time.Time) github.CloseOnMergeOptions { + return github.CloseOnMergeOptions{ + Identity: hiveIdentity(cfg), + Logger: logger, + TrustedAuthor: func(repo, login string) bool { + decision := trustedAuthorFunc(cfg)(login, cfg.AutoMerge.TrustedAuthors.EffectiveRequireRole()) + return decision.Allowed + }, + RecheckAfter: cfg.Issues.EffectiveCloseOnMergeRecheck(), + Now: now, + LabelDriven: cfg.RepoLabelDriven, + RepoOnGitHub: cfg.RepoOnGitHub, + } +} + func runCloseOnMergeSweep(ctx context.Context, cfg *config.Config, ghClient *github.Client, ledger *github.ClaimLedger, logger *slog.Logger) { runCloseOnMergeSweepWith(ctx, cfg, ghClient, ledger, logger, closeOnMergeSched) } @@ -114,19 +131,8 @@ func runCloseOnMergeSweepWith(ctx context.Context, cfg *config.Config, ghClient if plan.BudgetChanged && logger != nil { logger.Info("close-on-merge: sweeps resumed", "budget_mode", plan.Mode.String()) } - opts := github.CloseOnMergeOptions{ - Identity: hiveIdentity(cfg), - Logger: logger, - TrustedAuthor: func(repo, login string) bool { - decision := trustedAuthorFunc(cfg)(login, cfg.AutoMerge.TrustedAuthors.EffectiveRequireRole()) - return decision.Allowed - }, - RecheckAfter: cfg.Issues.EffectiveCloseOnMergeRecheck(), - MergedAfter: plan.MergedAfter, - Now: sched.clock(), - LabelDriven: cfg.RepoLabelDriven, - RepoOnGitHub: cfg.RepoOnGitHub, - } + opts := closeOnMergeOptionsFor(cfg, logger, sched.clock()) + opts.MergedAfter = plan.MergedAfter sweep := ghClient.CloseOnMergeLedgerSweep(ctx, ledger, opts) msg := "close-on-merge ledger sweep" if !plan.FullSweep { diff --git a/src/cmd/hive/eval_cycle_source.go b/src/cmd/hive/eval_cycle_source.go index 42d6d02273..8a7e5b00d8 100644 --- a/src/cmd/hive/eval_cycle_source.go +++ b/src/cmd/hive/eval_cycle_source.go @@ -137,7 +137,7 @@ func (b *boot) applyWebhookItemsFunc() func([]github.WebhookItemSnapshot) { } // A `pull_request` delivery's issue claims land in the ledger and // drop out of this snapshot on the event (hivecommons/hive#14814). - github.SetPRClaimsHook(prClaimsHookFor(func() *github.ClaimLedger { return getClaimLedger(b.logger) }, b.snapshotPatch, b.logger)) + github.SetPRClaimsHook(prClaimsHookFor(func() *github.ClaimLedger { return getClaimLedger(b.logger) }, b.snapshotPatch, b.logger, b.closeOnMergeForDelivery)) } return func(snaps []github.WebhookItemSnapshot) { b.snapshotPatch.apply(snaps) } } diff --git a/src/cmd/hive/github_client_config.go b/src/cmd/hive/github_client_config.go index 6db17e32be..92381fa6f9 100644 --- a/src/cmd/hive/github_client_config.go +++ b/src/cmd/hive/github_client_config.go @@ -141,6 +141,10 @@ func (b *boot) applyGitHubClientConfigHooks(client *github.Client) { // in-progress sweep: a ledger claim whose 🔒 comment was budget-suppressed // must still read as a claim (claimswire.go, ledgerClaimLookup). client.SetIssueClaimLedger(ledgerClaimLookup(func() *claims.Ledger { return b.issueClaims })) + // Duplicate-PR claim ledger fallback for the out-of-cycle stage facts: + // a claim release on an issue whose covering PR the ledger already holds + // re-derives 040, not 010 (stage_facts_sink.go, ledgerCoveringPR). + client.SetPRClaimLookup(b.prClaimCoverLookup()) // A marker this hive wrote is live only while its ledger still holds the // claim (hivecommons/hive#13579, issue_claims.go). The ledger itself is // built after this client (main.go), so the hive is resolved per call diff --git a/src/cmd/hive/main.go b/src/cmd/hive/main.go index aa52394fee..6575c1998b 100644 --- a/src/cmd/hive/main.go +++ b/src/cmd/hive/main.go @@ -7207,6 +7207,10 @@ func runEvalCycle( if !budgetDecision.SkipOptional { applyDuplicatePRGuard(ctx, cfg, ghClient, actionable, logger) } + // Every cycle, cached ones included: heal issue stage records the + // claim ledger says an open PR covers but the store still holds below + // 040 (a claim release written over the cover between reconcile passes). + reconcileLedgerCoverRecords(ctx, cfg, ghClient, actionable, logger) // PR review queue (#9590): stamp each PR's rank, priority and reasons // onto the snapshot so last-actionable.json carries them next to @@ -10119,6 +10123,26 @@ func recheckSoakHubURL(cfg *config.Config) string { // applyDuplicatePRGuard filters issues already claimed by an open hive-authored // PR out of the actionable set. Failures are logged, never fatal: the guard is // a safety net, and a broken net must not take the hive down with it. +// reconcileLedgerCoverRecords runs github.BackfillCoveredByLedger with the +// cycle's red+stale valve. It is not an optional step: with webhook-driven +// cached cycles the reconcile pass (and the stage sweep with it) can be +// hours apart, and a record at 010 under an open covering PR re-offers the +// issue to the scanner for all of that time. +func reconcileLedgerCoverRecords(ctx context.Context, cfg *config.Config, ghClient *github.Client, actionable *github.ActionableResult, logger *slog.Logger) { + ledger := getClaimLedger(logger) + if ledger == nil || ledger.Len() == 0 || ghClient == nil { + return + } + backfillCtx, cancel := context.WithTimeout(ctx, issueStageSyncTimeout) + defer cancel() + res := ghClient.BackfillCoveredByLedger(backfillCtx, ledger, claimingPRRedStale(cfg, actionable)) + if res.Covered+res.Errors > 0 && logger != nil { + logger.Info("stage backfill: issue records reconciled with the claim ledger", + "checked", res.Checked, "covered", res.Covered, "skipped_red_stale", res.SkippedRedStale, + "skipped_not_open", res.SkippedNotOpen, "errors", res.Errors) + } +} + func applyDuplicatePRGuard( ctx context.Context, cfg *config.Config, diff --git a/src/cmd/hive/webhook_pr_claims.go b/src/cmd/hive/webhook_pr_claims.go index 6f1c93fd5d..7b75adc71d 100644 --- a/src/cmd/hive/webhook_pr_claims.go +++ b/src/cmd/hive/webhook_pr_claims.go @@ -1,6 +1,7 @@ package main import ( + "context" "log/slog" "time" @@ -16,8 +17,10 @@ import ( // enumeration, for the contribute lane (which reads the ledger at offer // time) and the hub's own agents (which plan from the snapshot) alike. The // ledger is resolved per call because it loads lazily; a nil patcher skips -// the snapshot step. -func prClaimsHookFor(ledger func() *github.ClaimLedger, patch *snapshotPatcher, logger *slog.Logger) github.PRClaimsHook { +// the snapshot step. onMerged, when non-nil, runs after a MERGED delivery +// whose claims the ledger recorded, so the PR's issues close on the event +// (closeOnMergeForDelivery) rather than on the next reconcile pass. +func prClaimsHookFor(ledger func() *github.ClaimLedger, patch *snapshotPatcher, logger *slog.Logger, onMerged func(github.PRClaimDelivery)) github.PRClaimsHook { return func(d github.PRClaimDelivery) { if ledger == nil { return @@ -41,9 +44,45 @@ func prClaimsHookFor(ledger func() *github.ClaimLedger, patch *snapshotPatcher, "issues", d.ClaimedIssues(), "recorded", recorded, "released", released, "suppressed", suppressed, "source", "webhook") } + if onMerged != nil && d.State == github.PRStateMerged && recorded > 0 { + onMerged(d) + } + } +} + +// closeOnMergeForDelivery runs the close-on-merge ledger sweep for the one +// PR a MERGED `pull_request` delivery names, detached from the webhook +// handler and bounded by closeOnMergeDeliveryTimeout. Before this, an issue +// whose PR merged right after the reconcile pass's sweep waited for the next +// pass — hours, when webhook-driven cached cycles skip the optional sweeps — +// and in the meantime kept its stale stage record (hivecommons/hive#14646 +// sat at 010 under a PR merged at 12:54Z). The sweep re-reads the PR and the +// issue live and applies the same identity/trusted-author policy as the +// scheduled one; it does not need the sweep scheduler's cadence. +func (b *boot) closeOnMergeForDelivery(d github.PRClaimDelivery) { + cfg, client := b.cfg, b.ghClient + if cfg == nil || client == nil || !cfg.Issues.CloseOnMergeEnabled() || d.Number <= 0 { + return + } + ledger := getClaimLedger(b.logger) + parent := b.ctx + if parent == nil { + parent = context.Background() } + go func() { + ctx, cancel := context.WithTimeout(parent, closeOnMergeDeliveryTimeout) + defer cancel() + opts := closeOnMergeOptionsFor(cfg, b.logger, time.Now) + opts.OnlyPRRepo, opts.OnlyPRNumber = d.Repo, d.Number + sweep := client.CloseOnMergeLedgerSweep(ctx, ledger, opts) + logCloseOnMergeResults(b.logger, "close-on-merge webhook sweep", sweep.Results) + }() } +// closeOnMergeDeliveryTimeout bounds one webhook-triggered close-on-merge +// sweep: a handful of reads and at most a few closes. +const closeOnMergeDeliveryTimeout = 2 * time.Minute + // suppressClaimed re-filters the stored actionable snapshot against the // claim ledger, copy-on-write, and reports how many issues it dropped. The // red+stale release valve is not consulted: a claim the webhook just @@ -75,3 +114,25 @@ func (p *snapshotPatcher) suppressClaimed(ledger *github.ClaimLedger, logger *sl } return suppressed } + +// prClaimCoverLookup is the github.Client's read of the duplicate-PR claim +// ledger for the stage-fact sink: the ledger's live claim on (repo, issue), +// unless the claiming PR is red and stale on this spoke's last snapshot, in +// which case FilterClaimedIssues would have released the issue and the +// fact sink must not re-cover it. The ledger loads lazily, so it is +// resolved per call. +func (b *boot) prClaimCoverLookup() func(repo string, number int) (github.IssueClaim, bool) { + return func(repo string, number int) (github.IssueClaim, bool) { + ledger := getClaimLedger(b.logger) + claim, ok := ledger.Lookup(repo, number) + if !ok { + return github.IssueClaim{}, false + } + if b.cfg != nil && !claim.MergedPR { + if redStale := claimingPRRedStale(b.cfg, b.lastActionable.Load()); redStale != nil && redStale(claim.PRRepo, claim.PRNumber) { + return github.IssueClaim{}, false + } + } + return claim, true + } +} diff --git a/src/cmd/hive/webhook_pr_claims_test.go b/src/cmd/hive/webhook_pr_claims_test.go index f560be269a..8f53baad4a 100644 --- a/src/cmd/hive/webhook_pr_claims_test.go +++ b/src/cmd/hive/webhook_pr_claims_test.go @@ -27,7 +27,7 @@ func TestPRClaimsHookRecordsAndFiltersSnapshot(t *testing.T) { var patched []int patch := &snapshotPatcher{target: &target, logger: logger, onPatch: func(n int) { patched = append(patched, n) }} - hook := prClaimsHookFor(func() *github.ClaimLedger { return ledger }, patch, logger) + hook := prClaimsHookFor(func() *github.ClaimLedger { return ledger }, patch, logger, nil) hook(github.PRClaimDelivery{ Repo: "repo", Number: 14772, Action: "opened", State: github.PRStateOpen, At: now, Claims: []github.IssueClaim{{Repo: "repo", Issue: 14765, PRNumber: 14772, PRRepo: "repo", PRAuthor: "owner", ExternalAuthor: true, ObservedAt: now}}, @@ -59,9 +59,38 @@ func TestPRClaimsHookRecordsAndFiltersSnapshot(t *testing.T) { } // Nil ledger resolver / nil patcher are safe. - prClaimsHookFor(nil, nil, logger)(github.PRClaimDelivery{Repo: "repo", Number: 1}) - prClaimsHookFor(func() *github.ClaimLedger { return nil }, nil, logger)(github.PRClaimDelivery{Repo: "repo", Number: 1}) + prClaimsHookFor(nil, nil, logger, nil)(github.PRClaimDelivery{Repo: "repo", Number: 1}) + prClaimsHookFor(func() *github.ClaimLedger { return nil }, nil, logger, nil)(github.PRClaimDelivery{Repo: "repo", Number: 1}) if (*snapshotPatcher)(nil).suppressClaimed(ledger, logger) != 0 { t.Fatal("nil patcher must be a no-op") } } + +// A MERGED delivery whose claims the ledger recorded hands the PR to the +// close-on-merge path at once; an open delivery and a merged one with +// nothing to record do not (hivecommons/hive#14646 waited on the next +// reconcile pass for its close). +func TestPRClaimsHookRunsCloseOnMergeForMergedDelivery(t *testing.T) { + logger := slog.New(slog.NewTextHandler(io.Discard, nil)) + now := time.Now().UTC() + ledger := github.NewClaimLedger(filepath.Join(t.TempDir(), "claims.json"), logger) + var merged []int + hook := prClaimsHookFor(func() *github.ClaimLedger { return ledger }, nil, logger, func(d github.PRClaimDelivery) { merged = append(merged, d.Number) }) + + claims := []github.IssueClaim{{Repo: "repo", Issue: 14646, PRNumber: 14920, PRRepo: "repo", PRAuthor: "dev", ExternalAuthor: true, ObservedAt: now}} + hook(github.PRClaimDelivery{Repo: "repo", Number: 14920, Action: "opened", State: github.PRStateOpen, At: now, Claims: claims}) + if len(merged) != 0 { + t.Fatalf("open delivery triggered close-on-merge: %v", merged) + } + hook(github.PRClaimDelivery{Repo: "repo", Number: 14920, Action: "closed", State: github.PRStateMerged, MergedAt: now, At: now, Claims: claims}) + if len(merged) != 1 || merged[0] != 14920 { + t.Fatalf("close-on-merge calls = %v, want [14920]", merged) + } + if c, ok := ledger.Lookup("repo", 14646); !ok || !c.MergedPR { + t.Fatalf("ledger claim after merge = %+v ok=%v, want merged", c, ok) + } + hook(github.PRClaimDelivery{Repo: "repo", Number: 99, Action: "closed", State: github.PRStateMerged, MergedAt: now, At: now}) + if len(merged) != 1 { + t.Fatalf("merged delivery with no claims triggered close-on-merge: %v", merged) + } +} diff --git a/src/pkg/github/client.go b/src/pkg/github/client.go index 8772c1b196..ae667f8dc3 100644 --- a/src/pkg/github/client.go +++ b/src/pkg/github/client.go @@ -209,6 +209,11 @@ type Client struct { // carries no live marker: the 🔒 comment is budgeted and can be // suppressed, and a claim the ledger holds must still read as a claim. issueClaimLedger func(repo string, number int) (issueclaim.Claim, bool) + // prClaimLookup resolves the duplicate-PR claim ledger's record for an + // issue (SetPRClaimLookup). An out-of-cycle fact on an issue the ledger + // knows an open PR covers re-derives under that PR (stage_facts_sink.go, + // enrichCoveringPR) instead of falling to 010/020 until the next sweep. + prClaimLookup func(repo string, number int) (IssueClaim, bool) // issueClaimLedgerHive is the hive= this hub writes on its own markers; // a live forge marker carrying it while the ledger holds nothing is a // marker the hub already released (hivecommons/hive#13579). diff --git a/src/pkg/github/close_on_merge.go b/src/pkg/github/close_on_merge.go index f56d28b388..8ef83473d5 100644 --- a/src/pkg/github/close_on_merge.go +++ b/src/pkg/github/close_on_merge.go @@ -53,6 +53,13 @@ type CloseOnMergeOptions struct { MergedAfter time.Time // Now is the clock; nil means time.Now. Now func() time.Time + // OnlyPRRepo/OnlyPRNumber, when OnlyPRNumber is set, restrict the ledger + // sweep to the claims one pull request makes: the webhook path, which + // closes a just-merged PR's issues on the delivery instead of waiting for + // the reconcile pass (whose sweep a cached cycle skips). OnlyPRRepo is + // matched by bare repository name; empty matches any. + OnlyPRRepo string + OnlyPRNumber int // LabelDriven reports a repo that opted in to label-driven triage; the // backfill posts no "What to reply" notice there when it reclassifies a // dedupe checklist as needs-decision. nil means no repo opts in. @@ -76,6 +83,25 @@ func (o CloseOnMergeOptions) onGitHub(repo string) bool { return o.RepoOnGitHub == nil || o.RepoOnGitHub(repo) } +// wantsPR reports whether the OnlyPR filter admits a claim by (repo, number). +func (o CloseOnMergeOptions) wantsPR(repo string, number int) bool { + if o.OnlyPRNumber <= 0 { + return true + } + if number != o.OnlyPRNumber { + return false + } + return o.OnlyPRRepo == "" || strings.EqualFold(bareRepo(o.OnlyPRRepo), bareRepo(repo)) +} + +// bareRepo strips an owner/ prefix. +func bareRepo(repo string) string { + if i := strings.LastIndex(repo, "/"); i >= 0 { + return repo[i+1:] + } + return repo +} + func (o CloseOnMergeOptions) recheckAfter() time.Duration { if o.RecheckAfter <= 0 { return DefaultCloseOnMergeRecheck @@ -194,7 +220,7 @@ func (c *Client) CloseOnMergeLedgerSweep(ctx context.Context, ledger *ClaimLedge if !claim.MergedPR || claim.PRNumber <= 0 || claim.Issue <= 0 || strings.TrimSpace(claim.Repo) == "" { continue } - if claim.Reference { + if claim.Reference || !opts.wantsPR(claim.PRRepo, claim.PRNumber) { continue } if !opts.onGitHub(claim.Repo) || (claim.PRRepo != "" && !opts.onGitHub(claim.PRRepo)) { diff --git a/src/pkg/github/close_on_merge_forge_test.go b/src/pkg/github/close_on_merge_forge_test.go index 646b187266..391633efb1 100644 --- a/src/pkg/github/close_on_merge_forge_test.go +++ b/src/pkg/github/close_on_merge_forge_test.go @@ -72,3 +72,40 @@ func TestCloseOnMergeBackfillSkipsOtherForgeRepos(t *testing.T) { t.Fatalf("results = %+v, want none", results) } } + +// The webhook path restricts the ledger sweep to the PR that just merged: +// the other merged claims cost no API call and stay unsettled for the +// scheduled sweep. +func TestCloseOnMergeLedgerSweepOnlyPRFilter(t *testing.T) { + defer resetPRDetailCacheForTest(nil, 0)() + f := newLedgerSweepFixture(t, 7, 8) + srv := f.server() + defer srv.Close() + ledger := NewClaimLedger(filepath.Join(t.TempDir(), "ledger.json"), nil) + merged := time.Date(2026, 10, 9, 12, 0, 0, 0, time.UTC) + for _, issue := range []int{7, 8} { + if err := ledger.Record(mergedLedgerClaim(issue, merged)); err != nil { + t.Fatal(err) + } + } + c := newTestClient(t, srv, "o", []string{"r"}) + opts := CloseOnMergeOptions{ + Identity: HiveIdentity{AppLogin: "hive[bot]"}, + Now: func() time.Time { return merged.Add(time.Hour) }, + OnlyPRRepo: "r", + OnlyPRNumber: 8, + } + + sweep := c.CloseOnMergeLedgerSweep(context.Background(), ledger, opts) + if len(sweep.Results) != 1 || sweep.Results[0].Issue != 8 || sweep.Results[0].Action != CloseOnMergeClosed { + t.Fatalf("results = %+v, want only issue 8 closed", sweep.Results) + } + if got := f.count("pull_get"); got != 1 { + t.Fatalf("PR GETs = %d, want 1", got) + } + for _, claim := range ledger.Claims() { + if settled := !claim.CloseOnMergeSettledAt.IsZero(); settled != (claim.Issue == 8) { + t.Fatalf("claim %d settled=%v", claim.Issue, settled) + } + } +} diff --git a/src/pkg/github/prclaims.go b/src/pkg/github/prclaims.go index f4d5ba940a..f0c3c7aca8 100644 --- a/src/pkg/github/prclaims.go +++ b/src/pkg/github/prclaims.go @@ -319,6 +319,18 @@ func (c IssueClaim) Settled() bool { return c.MergedPR && !c.Reference && !c.ExternalAuthor } +// CoversOpenIssue reports whether the claim is one FilterClaimedIssues +// suppresses the issue for: an OPEN pull request that either closes the +// issue or was opened by someone other than this hive. A merged claim is a +// verification matter, a hive-authored non-closing reference only annotates. +// The red+stale release valve is not part of this predicate. +func (c IssueClaim) CoversOpenIssue() bool { + if c.PRNumber <= 0 || c.MergedPR { + return false + } + return c.ExternalAuthor || !c.Reference +} + // SettledAt is the instant the settled evidence was produced: the merge for // a merged-PR claim, otherwise the first observation. Zero for an unsettled // claim. diff --git a/src/pkg/github/stage_facts_sink.go b/src/pkg/github/stage_facts_sink.go index 1e558fb976..c21ac9e3f2 100644 --- a/src/pkg/github/stage_facts_sink.go +++ b/src/pkg/github/stage_facts_sink.go @@ -175,7 +175,8 @@ func (c *Client) enrichStageFacts(ctx context.Context, f stageengine.Facts) (sta // claim side of the story; without this step each re-derived 020 or 010 // under the PR, the store booked a regression and the activity monitor // showed "regressed" until the next sweep put 040 back. The store's memory -// of the covering PR (Record.CoveringPR) is only trusted after a fresh +// of the covering PR (Record.CoveringPR), or failing that the duplicate-PR +// claim ledger's (ledgerCoveringPR), is only trusted after a fresh // read says the PR is still open and unmerged; a read failure is the // fact's error (the labels stand until the sweep converges them) rather // than a spurious fall. An Uncovered fact names the PR that closed, and @@ -189,11 +190,10 @@ func (c *Client) enrichCoveringPR(ctx context.Context, store *stagelabels.Store, default: return f, nil } - rec, ok := store.Get(f.Ref.Key()) - if !ok || rec.Stage != stagelabels.CoveredByPR || rec.CoveringPR == "" { - return f, nil + pr, ok := c.rememberedCoveringPR(store, f.Ref) + if !ok { + pr, ok = c.ledgerCoveringPR(f.Ref) } - pr, ok := parseStoreKeyRef(rec.CoveringPR) if !ok || (f.Issue.ClosedPR != nil && f.Issue.ClosedPR.Key() == pr.Key()) { return f, nil } @@ -216,6 +216,52 @@ func (c *Client) enrichCoveringPR(ctx context.Context, store *stagelabels.Store, return f, nil } +// rememberedCoveringPR is the store's memory of the issue's covering PR: a +// 040 record naming it. +func (c *Client) rememberedCoveringPR(store *stagelabels.Store, issue stageengine.Ref) (stageengine.Ref, bool) { + rec, ok := store.Get(issue.Key()) + if !ok || rec.Stage != stagelabels.CoveredByPR || rec.CoveringPR == "" { + return stageengine.Ref{}, false + } + return parseStoreKeyRef(rec.CoveringPR) +} + +// ledgerCoveringPR is the duplicate-PR claim ledger's answer to "which open +// PR covers this issue" (SetPRClaimLookup), consulted when the store has no +// 040 record yet. That is the case for every issue whose covering PR opened +// while the issue carried a live claim: the sweep had booked 020, the PR's +// webhook delivery recorded the claim in the ledger, and the ClaimReleased +// fact that followed (lease revoked once the PR covered the work) had no +// memory to fall back on and re-derived 010 — nine issues sat at +// stage/010-actionable with bucket=claimed_by_pr for hours while cached +// cycles planned around them. Only a claim FilterClaimedIssues would +// suppress the issue for counts (IssueClaim.CoversOpenIssue); the ledger is +// keyed by the configured repo spelling, so both the bare and the +// owner-qualified name are tried. +func (c *Client) ledgerCoveringPR(issue stageengine.Ref) (stageengine.Ref, bool) { + if c == nil || c.prClaimLookup == nil || !issue.IsDefaultSource() { + return stageengine.Ref{}, false + } + claim, ok := c.prClaimLookup(issue.Repo, issue.Number) + if !ok && issue.Owner != "" { + claim, ok = c.prClaimLookup(issue.Owner+"/"+issue.Repo, issue.Number) + } + if !ok || !claim.CoversOpenIssue() { + return stageengine.Ref{}, false + } + return c.claimPRRef(claim, issue) +} + +// SetPRClaimLookup installs the duplicate-PR claim ledger read the fact sink +// uses to keep an open covering PR in the picture for out-of-cycle facts +// (enrichCoveringPR). Resolved per call; nil disables the fallback. +func (c *Client) SetPRClaimLookup(fn func(repo string, number int) (IssueClaim, bool)) { + if c == nil { + return + } + c.prClaimLookup = fn +} + // parseStoreKeyRef turns a default-source store key ("owner/repo#n") back // into a PR Ref. Keys of another forge ("source:owner/repo#n") and // malformed keys report false. diff --git a/src/pkg/github/stage_ledger_backfill.go b/src/pkg/github/stage_ledger_backfill.go new file mode 100644 index 0000000000..8213e4b82b --- /dev/null +++ b/src/pkg/github/stage_ledger_backfill.go @@ -0,0 +1,131 @@ +package github + +import ( + "context" + "fmt" + "strings" + + "github.com/hivecommons/hive/pkg/stageengine" + "github.com/hivecommons/hive/pkg/stagelabels" +) + +// LedgerCoverBackfill is one BackfillCoveredByLedger pass. +type LedgerCoverBackfill struct { + // Checked counts ledger claims an open PR makes on an issue the store + // holds below 040. + Checked int + // Covered counts issues moved to 040 under their covering PR. + Covered int + // SkippedRedStale counts issues the red+stale valve kept released. + SkippedRedStale int + // SkippedNotOpen counts claims whose PR the fresh read found closed or + // merged; the ledger catches up on its own. + SkippedNotOpen int + Errors int +} + +// BackfillCoveredByLedger reconciles the stage store with the duplicate-PR +// claim ledger: every issue the ledger says an OPEN pull request covers +// (IssueClaim.CoversOpenIssue — the same claims FilterClaimedIssues buckets +// claimed_by_pr) whose store record still sits below 040 gets a CoveredBy +// fact, after a fresh read confirms the PR is open and unmerged. The sweep +// derives the same answer, but it only runs on the reconcile pass; between +// passes, a claim release on a covered issue used to write 010 over the +// ledger's 040 and the record then stayed wrong for hours (nine issues on +// the hosted spoke, hivecommons/hive#14910 et al.). This pass is cheap when +// the two agree — a ledger walk against the in-memory store, no API call — +// so it runs on every cycle, cached ones included, and at startup. redStale +// (nil = never) is the same release valve the guard applies, so an issue the +// guard released for a red, stale PR is not re-covered here. Issues the store +// has never seen are left to the sweep: the record is the evidence that the +// engine owns the item. +func (c *Client) BackfillCoveredByLedger(ctx context.Context, ledger *ClaimLedger, redStale RedStaleFunc) LedgerCoverBackfill { + var res LedgerCoverBackfill + if c == nil || c.client == nil || ledger == nil || ledger.Len() == 0 || !c.issueStagePolicy().Enabled { + return res + } + store := stagelabels.Shared() + for _, claim := range ledger.Claims() { + if !claim.CoversOpenIssue() || claim.Issue <= 0 || strings.TrimSpace(claim.Repo) == "" { + continue + } + if _, live := ledger.Lookup(claim.Repo, claim.Issue); !live { + continue + } + issue := c.IssueStageRef(claim.Repo, claim.Issue) + if !issue.IsDefaultSource() { + continue + } + rec, ok := store.Get(issue.Key()) + if !ok || !rec.Stage.Before(stagelabels.CoveredByPR) { + continue + } + res.Checked++ + if redStale != nil && redStale(claim.PRRepo, claim.PRNumber) { + res.SkippedRedStale++ + continue + } + pr, ok := c.claimPRRef(claim, issue) + if !ok { + continue + } + if ctx.Err() != nil { + res.Errors++ + return res + } + live, _, err := c.client.PullRequests.Get(WithRESTCaller(ctx, "hive:stage_backfill"), pr.Owner, pr.Repo, pr.Number) + if err != nil { + res.Errors++ + c.warnLedgerBackfill("reading covering PR failed", issue, pr, err) + continue + } + if strings.EqualFold(live.GetState(), "closed") || live.GetMerged() || !live.GetMergedAt().IsZero() { + res.SkippedNotOpen++ + continue + } + if err := c.EnsureCoveredByPRLabel(ctx, issue.FullRepo()); err != nil { + res.Errors++ + c.warnLedgerBackfill("ensuring covered-by-pr label failed", issue, pr, err) + continue + } + if err := c.StageFacts().CoveredBy(ctx, issue, pr); err != nil { + res.Errors++ + c.warnLedgerBackfill("moving issue to covered-by-pr failed", issue, pr, err) + continue + } + res.Covered++ + if c.logger != nil { + c.logger.Info("stage backfill: issue record disagreed with the claim ledger; covered by its open PR", + "issue", issue.String(), "pr", pr.String(), "was", rec.Stage.Slug()) + } + } + return res +} + +// claimPRRef is the engine Ref of the pull request a ledger claim names. +// PRRepo may be bare (the configured spelling) or owner-qualified, or empty +// for a claim on the PR's own repository. +func (c *Client) claimPRRef(claim IssueClaim, issue stageengine.Ref) (stageengine.Ref, bool) { + if claim.PRNumber <= 0 { + return stageengine.Ref{}, false + } + prRepo := claim.PRRepo + if prRepo == "" { + prRepo = claim.Repo + } + owner, name := c.splitRepo(prRepo) + if owner == "" { + owner = issue.Owner + } + if owner == "" || name == "" { + return stageengine.Ref{}, false + } + return stageengine.Ref{Owner: owner, Repo: name, Number: claim.PRNumber, Kind: stagelabels.PRItem}, true +} + +func (c *Client) warnLedgerBackfill(what string, issue, pr stageengine.Ref, err error) { + if c.logger == nil { + return + } + c.logger.Warn(fmt.Sprintf("stage backfill: %s", what), "issue", issue.String(), "pr", pr.String(), "error", err) +} diff --git a/src/pkg/github/stage_ledger_backfill_test.go b/src/pkg/github/stage_ledger_backfill_test.go new file mode 100644 index 0000000000..1bed80e6a2 --- /dev/null +++ b/src/pkg/github/stage_ledger_backfill_test.go @@ -0,0 +1,264 @@ +package github + +import ( + "context" + "io" + "log/slog" + "path/filepath" + "testing" + "time" + + "github.com/hivecommons/hive/pkg/claims" + "github.com/hivecommons/hive/pkg/stageengine" + "github.com/hivecommons/hive/pkg/stagelabels" +) + +// claimedIssue seeds the shared store with o/r#7 at 020 under a live claim +// and no memory of any covering PR — the state a covered issue was in when +// its PR's webhook landed in the ledger but no stage fact followed. +func claimedIssue(t *testing.T, c *Client) stageengine.Ref { + t.Helper() + store := stagelabels.Shared() + issue := c.IssueStageRef("o/r", 7) + store.Observe(issue.Key(), stagelabels.Claimed, "live issue claim") + t.Cleanup(func() { store.Forget(issue.Key()); store.Forget(c.PRStageRef("o/r", 8).Key()) }) + return issue +} + +func ledgerLookupFor(claim IssueClaim, ok bool) func(repo string, number int) (IssueClaim, bool) { + return func(repo string, number int) (IssueClaim, bool) { + if number != claim.Issue || (repo != claim.Repo && repo != "o/"+claim.Repo) { + return IssueClaim{}, false + } + return claim, ok + } +} + +// hivecommons/hive#14910 et al.: the store holds 020 and nothing about a +// covering PR, the claim ledger holds the open PR that fixes the issue +// (recorded from its webhook), and the claim is released. The release must +// re-derive 040 under that PR, not fall to 010. +func TestStageFacts_ClaimReleaseUnderLedgerCoveringPRDerives040(t *testing.T) { + srv := newStageFactsServer(t, "help wanted", stagelabels.Claimed.Label()) + c := testClient(t, srv.srv.URL) + c.coveredByPRLabel.mark("o/r") + issue := claimedIssue(t, c) + c.SetPRClaimLookup(ledgerLookupFor(IssueClaim{Repo: "r", Issue: 7, PRNumber: 8, PRRepo: "r", PRAuthor: "hive[bot]", Closing: true}, true)) + + if err := c.StageFacts().ClaimReleased(context.Background(), issue, "mendezr"); err != nil { + t.Fatal(err) + } + labels, _, _ := srv.snapshot() + if stagelabels.Current(labels) != stagelabels.CoveredByPR { + t.Fatalf("labels after release = %v, want 040", labels) + } + rec, _ := stagelabels.Shared().Get(issue.Key()) + if rec.Stage != stagelabels.CoveredByPR || rec.CoveringPR != c.PRStageRef("o/r", 8).Key() { + t.Fatalf("record after release = %+v, want 040 naming o/r#8", rec) + } + if srv.prReads != 1 { + t.Fatalf("covering PR read %d times, want once (liveness check)", srv.prReads) + } +} + +// The same release under an EXTERNAL contributor's open PR: the guard +// buckets it claimed_by_pr too, so the fact lands on 040 as well. +func TestStageFacts_ClaimReleaseUnderExternalLedgerClaimDerives040(t *testing.T) { + srv := newStageFactsServer(t, stagelabels.Claimed.Label()) + c := testClient(t, srv.srv.URL) + c.coveredByPRLabel.mark("o/r") + issue := claimedIssue(t, c) + c.SetPRClaimLookup(ledgerLookupFor(IssueClaim{Repo: "o/r", Issue: 7, PRNumber: 8, PRRepo: "o/r", PRAuthor: "mendezr", ExternalAuthor: true, Reference: true}, true)) + + if err := c.StageFacts().ClaimReleased(context.Background(), issue, "mendezr"); err != nil { + t.Fatal(err) + } + if labels, _, _ := srv.snapshot(); stagelabels.Current(labels) != stagelabels.CoveredByPR { + t.Fatalf("labels = %v, want 040", labels) + } +} + +// Ledger claims the guard does not suppress for are no cover: a hive +// non-closing reference annotates, a merged claim is a verification matter. +// Neither costs a PR read, and the release derives 010 as before. +func TestStageFacts_ClaimReleaseIgnoresWeakAndMergedLedgerClaims(t *testing.T) { + for name, claim := range map[string]IssueClaim{ + "reference": {Repo: "r", Issue: 7, PRNumber: 8, PRRepo: "r", Reference: true}, + "merged": {Repo: "r", Issue: 7, PRNumber: 8, PRRepo: "r", MergedPR: true, MergedAt: time.Now()}, + } { + t.Run(name, func(t *testing.T) { + srv := newStageFactsServer(t, stagelabels.Claimed.Label()) + c := testClient(t, srv.srv.URL) + issue := claimedIssue(t, c) + c.SetPRClaimLookup(ledgerLookupFor(claim, true)) + + if err := c.StageFacts().ClaimReleased(context.Background(), issue, "mendezr"); err != nil { + t.Fatal(err) + } + if labels, _, _ := srv.snapshot(); stagelabels.Current(labels) != stagelabels.Actionable { + t.Fatalf("labels = %v, want 010", labels) + } + if srv.prReads != 0 { + t.Fatalf("PR read %d times for a non-covering claim", srv.prReads) + } + }) + } +} + +// A ledger claim whose PR the fresh read finds closed is stale; the fact +// derives what it says and the store does not learn a cover. +func TestStageFacts_ClaimUnderClosedLedgerPRDerivesClaimed(t *testing.T) { + srv := newStageFactsServer(t, stagelabels.Actionable.Label()) + srv.prState = "closed" + c := testClient(t, srv.srv.URL) + issue := c.IssueStageRef("o/r", 7) + t.Cleanup(func() { stagelabels.Shared().Forget(issue.Key()) }) + c.SetPRClaimLookup(ledgerLookupFor(IssueClaim{Repo: "r", Issue: 7, PRNumber: 8, PRRepo: "r"}, true)) + + if err := c.StageFacts().Claimed(context.Background(), issue, stageengine.ClaimFact{Holder: "mendezr", Kind: claims.KindContributor}); err != nil { + t.Fatal(err) + } + if labels, _, _ := srv.snapshot(); stagelabels.Current(labels) != stagelabels.Claimed { + t.Fatalf("labels = %v, want 020", labels) + } + if rec, _ := stagelabels.Shared().Get(issue.Key()); rec.CoveringPR != "" { + t.Fatalf("closed PR remembered as cover: %q", rec.CoveringPR) + } +} + +func TestIssueClaimCoversOpenIssue(t *testing.T) { + cases := []struct { + name string + claim IssueClaim + want bool + }{ + {"hive closing", IssueClaim{PRNumber: 1, Closing: true}, true}, + {"hive plain", IssueClaim{PRNumber: 1}, true}, + {"hive reference", IssueClaim{PRNumber: 1, Reference: true}, false}, + {"external reference", IssueClaim{PRNumber: 1, Reference: true, ExternalAuthor: true}, true}, + {"external closing", IssueClaim{PRNumber: 1, ExternalAuthor: true}, true}, + {"merged", IssueClaim{PRNumber: 1, MergedPR: true}, false}, + {"no pr", IssueClaim{}, false}, + } + for _, tc := range cases { + if got := tc.claim.CoversOpenIssue(); got != tc.want { + t.Errorf("%s: CoversOpenIssue = %v, want %v", tc.name, got, tc.want) + } + } +} + +func backfillLedger(t *testing.T, claims ...IssueClaim) *ClaimLedger { + t.Helper() + ledger := NewClaimLedger(filepath.Join(t.TempDir(), "claims.json"), slog.New(slog.NewTextHandler(io.Discard, nil))) + for _, c := range claims { + if c.ObservedAt.IsZero() { + c.ObservedAt = time.Now() + } + if err := ledger.Record(c); err != nil { + t.Fatal(err) + } + } + return ledger +} + +// The backfill: a record below 040 under a ledger claim an open PR makes is +// moved to 040 (one PR read, one label write); a record already at 040 and +// an issue the store never saw cost nothing. +func TestBackfillCoveredByLedger_HealsRecordBelow040(t *testing.T) { + srv := newStageFactsServer(t, "help wanted", stagelabels.Actionable.Label()) + c := testClient(t, srv.srv.URL) + c.coveredByPRLabel.mark("o/r") + c.SetIssueStageLabels(func() IssueStagePolicy { return IssueStagePolicy{Enabled: true} }) + store := stagelabels.Shared() + issue := c.IssueStageRef("o/r", 7) + store.Observe(issue.Key(), stagelabels.Actionable, "actionable") + covered := c.IssueStageRef("o/r", 9) + store.Observe(covered.Key(), stagelabels.CoveredByPR, "open PR covers it") + t.Cleanup(func() { + store.Forget(issue.Key()) + store.Forget(covered.Key()) + store.Forget(c.PRStageRef("o/r", 8).Key()) + }) + ledger := backfillLedger(t, + IssueClaim{Repo: "r", Issue: 7, PRNumber: 8, PRRepo: "r", Closing: true}, + IssueClaim{Repo: "r", Issue: 9, PRNumber: 8, PRRepo: "r", Closing: true}, + IssueClaim{Repo: "r", Issue: 11, PRNumber: 8, PRRepo: "r", Closing: true}, + ) + + res := c.BackfillCoveredByLedger(context.Background(), ledger, nil) + if res.Checked != 1 || res.Covered != 1 || res.Errors != 0 { + t.Fatalf("backfill = %+v, want checked=1 covered=1", res) + } + rec, _ := store.Get(issue.Key()) + if rec.Stage != stagelabels.CoveredByPR || rec.CoveringPR != c.PRStageRef("o/r", 8).Key() { + t.Fatalf("record = %+v, want 040 under o/r#8", rec) + } + if labels, _, _ := srv.snapshot(); stagelabels.Current(labels) != stagelabels.CoveredByPR { + t.Fatalf("labels = %v, want 040", labels) + } + if srv.prReads != 1 { + t.Fatalf("PR read %d times, want once", srv.prReads) + } + + // Converged: a second pass is a no-op without an API call. + res = c.BackfillCoveredByLedger(context.Background(), ledger, nil) + if res.Checked != 0 || srv.prReads != 1 { + t.Fatalf("second pass = %+v prReads=%d, want nothing to do", res, srv.prReads) + } +} + +// The red+stale valve the guard applies holds here too, and a claim whose PR +// turns out merged is left to close-on-merge. +func TestBackfillCoveredByLedger_RespectsRedStaleAndMerged(t *testing.T) { + srv := newStageFactsServer(t, stagelabels.Actionable.Label()) + c := testClient(t, srv.srv.URL) + c.SetIssueStageLabels(func() IssueStagePolicy { return IssueStagePolicy{Enabled: true} }) + store := stagelabels.Shared() + issue := c.IssueStageRef("o/r", 7) + store.Observe(issue.Key(), stagelabels.Actionable, "actionable") + t.Cleanup(func() { store.Forget(issue.Key()) }) + ledger := backfillLedger(t, IssueClaim{Repo: "r", Issue: 7, PRNumber: 8, PRRepo: "r", Closing: true}) + + res := c.BackfillCoveredByLedger(context.Background(), ledger, func(prRepo string, prNumber int) bool { return prNumber == 8 }) + if res.Checked != 1 || res.SkippedRedStale != 1 || res.Covered != 0 || srv.prReads != 0 { + t.Fatalf("red+stale pass = %+v prReads=%d", res, srv.prReads) + } + + srv.prMerged = true + res = c.BackfillCoveredByLedger(context.Background(), ledger, nil) + if res.Checked != 1 || res.SkippedNotOpen != 1 || res.Covered != 0 { + t.Fatalf("merged pass = %+v", res) + } + if rec, _ := store.Get(issue.Key()); rec.Stage != stagelabels.Actionable { + t.Fatalf("record = %+v, want untouched 010", rec) + } +} + +// With the issue-stage lane off nothing is written. +func TestBackfillCoveredByLedger_DisabledIsNoop(t *testing.T) { + srv := newStageFactsServer(t, stagelabels.Actionable.Label()) + c := testClient(t, srv.srv.URL) + store := stagelabels.Shared() + issue := c.IssueStageRef("o/r", 7) + store.Observe(issue.Key(), stagelabels.Actionable, "actionable") + t.Cleanup(func() { store.Forget(issue.Key()) }) + ledger := backfillLedger(t, IssueClaim{Repo: "r", Issue: 7, PRNumber: 8, PRRepo: "r", Closing: true}) + + if res := c.BackfillCoveredByLedger(context.Background(), ledger, nil); res != (LedgerCoverBackfill{}) || srv.prReads != 0 { + t.Fatalf("disabled pass = %+v prReads=%d", res, srv.prReads) + } +} + +func TestCloseOnMergeOptionsWantsPR(t *testing.T) { + any := CloseOnMergeOptions{} + if !any.wantsPR("hive", 1) { + t.Fatal("no filter must admit every PR") + } + only := CloseOnMergeOptions{OnlyPRRepo: "hivecommons/hive", OnlyPRNumber: 14920} + if !only.wantsPR("hive", 14920) || !only.wantsPR("hivecommons/hive", 14920) { + t.Fatal("bare and qualified spellings of the PR repo must match") + } + if only.wantsPR("hive", 14921) || only.wantsPR("crux", 14920) { + t.Fatal("another PR admitted") + } +} From d6516777018d215ca6a4ca72ffd587d2723a8599 Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Wed, 28 Oct 2026 11:07:37 -0400 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=93=96=20docs:=20re-anchor=20RankActi?= =?UTF-8?q?onableIssues=20citation=20after=20client.go=20field=20insertion?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andrew Anderson --- src/docs/scale-envelope.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/scale-envelope.md b/src/docs/scale-envelope.md index bb5566fbd0..b270ef9fc3 100644 --- a/src/docs/scale-envelope.md +++ b/src/docs/scale-envelope.md @@ -34,7 +34,7 @@ ones to: 2. **Truncation must preserve the prioritization signal, not cut an arbitrary slice.** This holds today and is easy to assume backwards: - Issues are sorted by actionable rank tier, then **oldest first** within each tier before any cap is applied - (`RankActionableIssues`, `src/pkg/github/client.go:4767-4777`, descending `AgeMinutes`). + (`RankActionableIssues`, `src/pkg/github/client.go:4772-4782`, descending `AgeMinutes`). - PRs are sorted by **review class then oldest-first within class** (`SortPullRequestsForReview`, `src/pkg/github/review_priority.go:334`; fixes → refactors/docs → tests).