From 395ad422e3f182458e2a37c981f0ca442d0768c8 Mon Sep 17 00:00:00 2001 From: Danathar <6772335+Danathar@users.noreply.github.com> Date: Tue, 17 Nov 2026 17:31:01 -0500 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=90=9B=20writeback:=20let=20the=20hiv?= =?UTF-8?q?e=20move=20a=20stage=20label=20it=20applied=20on=20a=20PR=20old?= =?UTF-8?q?er=20than=20the=20backfill=20cutoff?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The backfill guard refused every stage-label write on a PR created before the repo's cutoff, so a stage label the hive itself had put there froze at a stage the hive no longer believed (projectbluefin/utah-packages#1148 at stage/100-merge-queue while not queued, projectbluefin/utah#1274 at 074 while tracked at 085). The stage labeler now states Item.HiveAppliedStage when every stage/* label on such a PR was last applied by one of the hive's own accounts (one timeline read, only for a PR the guard would hold, memoised per label set). For KindStageLabel the gate then skips the backfill guard and nothing else (reason hive-applied-stage), following the hive-applied-block (#17991) and hive-applied-park (#18051) exceptions. The 085 escalation note asks with the same fact so it describes the move as it happens. Signed-off-by: Danathar <6772335+Danathar@users.noreply.github.com> Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1 --- .../fixed-backfill-hive-applied-stage.md | 1 + .../sweeps-and-operations.md | 15 ++ .../automerge/automerge_contributor_adopt.go | 10 +- .../automerge_stage_move_suppressed_test.go | 57 ++++- .../github/automerge/automerge_writeback.go | 26 ++ src/pkg/github/client.go | 5 + src/pkg/github/stage_label_hive_applied.go | 124 ++++++++++ .../github/stage_label_hive_applied_test.go | 227 ++++++++++++++++++ src/pkg/github/stage_labeler.go | 17 +- src/pkg/writeback/gate.go | 77 +++++- src/pkg/writeback/hive_applied_stage_test.go | 146 +++++++++++ src/pkg/writeback/kinds.go | 5 +- 12 files changed, 696 insertions(+), 14 deletions(-) create mode 100644 changelog.d/fixed-backfill-hive-applied-stage.md create mode 100644 src/pkg/github/stage_label_hive_applied.go create mode 100644 src/pkg/github/stage_label_hive_applied_test.go create mode 100644 src/pkg/writeback/hive_applied_stage_test.go diff --git a/changelog.d/fixed-backfill-hive-applied-stage.md b/changelog.d/fixed-backfill-hive-applied-stage.md new file mode 100644 index 0000000000..2a614bd761 --- /dev/null +++ b/changelog.d/fixed-backfill-hive-applied-stage.md @@ -0,0 +1 @@ +- A pull request older than the write-back gate's backfill cutoff no longer keeps a stage label the hive no longer believes. The backfill guard refused every stage-label write on such a PR, so a stage label the hive itself had applied stayed frozen (for example `stage/100-merge-queue` on a PR that was not queued) while the hive's own comments and dashboard tracked another stage. When every `stage/*` label on the PR was last applied by one of the hive's own accounts, the stage labeler now states that fact and the gate lets the hive move or remove its own label (decision reason `hive-applied-stage`). Only the backfill guard is lifted: the opt-in label, level, pause, repo mode and `own_only` still apply, a person's stage label stays untouched, and the 085 escalation note describes the move the same way. diff --git a/src/docs/operator-reference/sweeps-and-operations.md b/src/docs/operator-reference/sweeps-and-operations.md index 2feda4ff1d..da3cd24052 100644 --- a/src/docs/operator-reference/sweeps-and-operations.md +++ b/src/docs/operator-reference/sweeps-and-operations.md @@ -677,6 +677,21 @@ one line — `writeback: skipped N pre-existing items on (backfill off)` — and the dashboard shows "hive can now write to ``; N existing PRs were left untouched — enable backfill to process them". +The guard keeps the hive from *starting* to write on old items. Three +writes on an item the hive has already written to are upkeep of its own +state, so the guard does not apply to them: the blocked repair of a +`blocked` the hive applied (`hive-applied-block`), the park re-check note on +a park the hive applied (`hive-applied-park`), and a stage-label move on a PR +whose `stage/*` labels the hive applied (`hive-applied-stage`). For the last, +the stage labeler reads the PR's timeline once the guard would hold the +write (and again when its stage labels change, or after 30 minutes): every +`stage/*` label it carries must have been applied last by one of the hive's +own accounts. A stage label a person applied, or a PR with none, stays under +the guard. Only the guard is lifted: the opt-in label, the level, a pause, +the repo mode and `own_only` still decide the write as they would for a +newer PR. Such a write is not counted among the pre-existing items left +untouched. + ### Duplicate-write suppression Policy decides whether a kind may write to an item; the content layer under diff --git a/src/pkg/github/automerge/automerge_contributor_adopt.go b/src/pkg/github/automerge/automerge_contributor_adopt.go index af751aa48f..47e83e47d9 100644 --- a/src/pkg/github/automerge/automerge_contributor_adopt.go +++ b/src/pkg/github/automerge/automerge_contributor_adopt.go @@ -2421,7 +2421,7 @@ type adoptionEscape struct { // reason) first; failed is the warning logged on an error. Returns the // comments posted. func (c *Engine) postAdoptionEscalationNote(ctx context.Context, store *stagelabels.Store, key string, obs stageObservation, reason, body, failed string) (int, error) { - body = c.withStageMoveFact(obs, body) + body = c.withStageMoveFact(ctx, obs, body) if _, _, err := c.gh.Issues.CreateComment(ctx, obs.Owner, obs.Repo, obs.Number, &gh.IssueComment{Body: gh.Ptr(body)}); err != nil { c.warn(failed, "repo", obs.Display, "pr", obs.Number, "head", obs.HeadSHA, "reason", reason, "error", err) return 0, err @@ -2436,9 +2436,11 @@ func (c *Engine) postAdoptionEscalationNote(ctx context.Context, store *stagelab // `stage/085-needs-decision`" announced a label that never landed // (projectbluefin/fsdk-containers#491, projectbluefin/utah-packages#812). // The gate is asked without recording a refusal: the stage writer records -// its own when it tries. -func (c *Engine) withStageMoveFact(obs stageObservation, body string) string { - d := c.writebackGate().Decide(obs.Owner+"/"+obs.Repo, writebackItemForObservation(obs), writeback.KindStageLabel) +// its own when it tries. It is asked with the same hive-applied-stage fact +// the stage writer states, so an old PR whose stage label is the hive's own +// is announced as moving, as it now does. +func (c *Engine) withStageMoveFact(ctx context.Context, obs stageObservation, body string) string { + d := c.writebackGate().Decide(obs.Owner+"/"+obs.Repo, c.stageWriteItem(ctx, obs), writeback.KindStageLabel) if d.Allowed { return body } diff --git a/src/pkg/github/automerge/automerge_stage_move_suppressed_test.go b/src/pkg/github/automerge/automerge_stage_move_suppressed_test.go index 3eaafac4a8..826f83102e 100644 --- a/src/pkg/github/automerge/automerge_stage_move_suppressed_test.go +++ b/src/pkg/github/automerge/automerge_stage_move_suppressed_test.go @@ -44,7 +44,7 @@ func TestEscalationNoteSaysWhenTheStageLabelIsRefused(t *testing.T) { if !strings.Contains(body, "Moving to `"+label+"`") { t.Fatalf("fixture no longer announces the move:\n%s", body) } - got := e.withStageMoveFact(obs, body) + got := e.withStageMoveFact(context.Background(), obs, body) if strings.Contains(got, "Moving to `") { t.Fatalf("a refused label write is still announced as a move:\n%s", got) } @@ -55,7 +55,7 @@ func TestEscalationNoteSaysWhenTheStageLabelIsRefused(t *testing.T) { } opted := obs opted.Labels = []string{writeback.DefaultOptInLabel} - if got := e.withStageMoveFact(opted, body); got != body { + if got := e.withStageMoveFact(context.Background(), opted, body); got != body { t.Fatalf("an opted-in PR's note must be unchanged:\n%s", got) } }) @@ -64,7 +64,7 @@ func TestEscalationNoteSaysWhenTheStageLabelIsRefused(t *testing.T) { t.Fatalf("describing the move recorded %d suppression(s); the stage writer records its own", n) } // No gate installed: every write is allowed, the note is unchanged. - if got := (&Engine{transport: stubTransport{}}).withStageMoveFact(obs, notes["workflow refused"]); got != notes["workflow refused"] { + if got := (&Engine{transport: stubTransport{}}).withStageMoveFact(context.Background(), obs, notes["workflow refused"]); got != notes["workflow refused"] { t.Fatalf("no gate: note changed:\n%s", got) } } @@ -95,3 +95,54 @@ func TestPostedEscalationNoteSaysWhenTheStageLabelIsRefused(t *testing.T) { t.Fatalf("posted note announces a refused move:\n%s", posted) } } + +// hiveStageTransport is gatedTransport whose client says whether a PR's +// stage labels are the hive's own (hgithub.Client.HiveAppliedStageLabels). +type hiveStageTransport struct { + gatedTransport + applied bool + asked *int +} + +func (t hiveStageTransport) HiveAppliedStageLabels(context.Context, string, int, []string) bool { + *t.asked++ + return t.applied +} + +// projectbluefin/utah#1274: on a PR older than the backfill cutoff the note +// said the gate kept the hive's labels off, while the 074 on it was the +// hive's own. The stage writer now moves a stage label the hive applied, so +// the note asks with the same fact and announces the move; a person's stage +// label is still described as held by the backfill guard. A PR the guard +// does not cover is decided without asking. +func TestEscalationNoteAnnouncesTheMoveOfAHiveAppliedStageLabel(t *testing.T) { + firstSeen := time.Date(2026, 11, 1, 0, 0, 0, 0, time.UTC) + cfg := writeback.Config{Kinds: map[string]writeback.KindPolicyOverride{"stage_label": {RequireLabel: gh.Ptr(false)}}} + gate := writeback.New(cfg, writeback.Deps{LevelFor: func(string) int { return 6 }, Now: func() time.Time { return firstSeen }}, "") + gate.ObserveRepo("projectbluefin/utah") + obs := stageObservation{Display: "projectbluefin/utah", Owner: "projectbluefin", Repo: "utah", Number: 1274, HeadSHA: "abc1274", Author: "contributor", Labels: []string{"stage/074-adopted-by-hive"}, OpenedAt: firstSeen.Add(-time.Hour)} + body := AdoptionWorkflowRefusedComment(obs) + label := stagelabels.NeedsDecision.Label() + + asked := 0 + hive := &Engine{transport: hiveStageTransport{gatedTransport: gatedTransport{gate: gate}, applied: true, asked: &asked}} + if got := hive.withStageMoveFact(context.Background(), obs, body); got != body { + t.Fatalf("the hive's own stage label: note must announce the move unchanged:\n%s", got) + } + person := &Engine{transport: hiveStageTransport{gatedTransport: gatedTransport{gate: gate}, applied: false, asked: &asked}} + got := person.withStageMoveFact(context.Background(), obs, body) + if !strings.Contains(got, "would move this to `"+label+"`") || !strings.Contains(got, string(writeback.ReasonBackfill)) { + t.Fatalf("a person's stage label: note must say the backfill guard holds the move:\n%s", got) + } + if asked != 2 { + t.Fatalf("asked %d times, want once per old PR note", asked) + } + newer := obs + newer.OpenedAt = firstSeen.Add(time.Hour) + if got := person.withStageMoveFact(context.Background(), newer, body); got != body || asked != 2 { + t.Fatalf("a PR the guard does not cover: note changed or the fact was asked (asked=%d):\n%s", asked, got) + } + if n := len(gate.Recent()); n != 0 { + t.Fatalf("describing the move recorded %d suppression(s)", n) + } +} diff --git a/src/pkg/github/automerge/automerge_writeback.go b/src/pkg/github/automerge/automerge_writeback.go index 2bec8ca5f3..12d53b893b 100644 --- a/src/pkg/github/automerge/automerge_writeback.go +++ b/src/pkg/github/automerge/automerge_writeback.go @@ -1,6 +1,8 @@ package automerge import ( + "context" + "github.com/hivecommons/hive/pkg/writeback" ) @@ -40,3 +42,27 @@ func (c *Engine) writebackAllowed(repo string, item writeback.Item, kind writeba func writebackItemForObservation(obs stageObservation) writeback.Item { return writeback.Item{Number: obs.Number, IsPR: true, Author: obs.Author, Labels: obs.Labels, CreatedAt: obs.OpenedAt} } + +// hiveAppliedStageTransport is the optional transport hook that says whether +// a PR's stage labels are the hive's own (hgithub.Client.HiveAppliedStageLabels). +type hiveAppliedStageTransport interface { + HiveAppliedStageLabels(ctx context.Context, repo string, number int, labels []string) bool +} + +// stageWriteItem is the gate's view of obs for a stage-label write, with +// Item.HiveAppliedStage stated as the stage labeler states it: only for a +// PR the backfill guard would hold, so a note that describes the label move +// answers as the labeler's own write will. +func (c *Engine) stageWriteItem(ctx context.Context, obs stageObservation) writeback.Item { + item := writebackItemForObservation(obs) + t, ok := c.transport.(hiveAppliedStageTransport) + if !ok { + return item + } + repo := obs.Owner + "/" + obs.Repo + if !c.writebackGate().BackfillHolds(repo, item) { + return item + } + item.HiveAppliedStage = t.HiveAppliedStageLabels(ctx, repo, obs.Number, obs.Labels) + return item +} diff --git a/src/pkg/github/client.go b/src/pkg/github/client.go index 2439875b38..c717556c67 100644 --- a/src/pkg/github/client.go +++ b/src/pkg/github/client.go @@ -645,6 +645,11 @@ type Client struct { // baseRefresh is the decision carry's memo (pr_decision_base_refresh.go). baseRefreshOnce sync.Once baseRefresh *BaseRefreshChecker + // hiveStage memoises who applied each held PR's stage labels + // (stage_label_hive_applied.go), so a PR the backfill guard holds costs + // one timeline read per label change, not one per stage sync. + hiveStageMu sync.Mutex + hiveStage map[string]hiveStageFact } func (c *Client) SetCanaryScanner(enabled, failClosed bool, reg *ioscan.CanaryRegistry, onLeak func(ioscan.CanaryLeak)) { diff --git a/src/pkg/github/stage_label_hive_applied.go b/src/pkg/github/stage_label_hive_applied.go new file mode 100644 index 0000000000..fb31e69810 --- /dev/null +++ b/src/pkg/github/stage_label_hive_applied.go @@ -0,0 +1,124 @@ +package github + +import ( + "context" + "sort" + "strconv" + "strings" + "time" + + "github.com/hivecommons/hive/pkg/stagelabels" + "github.com/hivecommons/hive/pkg/writeback" +) + +// A PR older than the write-back gate's backfill cutoff keeps the stage +// labels it has: the guard refuses every stage write on it, the move to a +// new stage and the removal of the old one alike. When those labels are the +// hive's own, that freezes a stage the hive no longer believes on GitHub +// (projectbluefin/utah-packages#1148 at stage/100-merge-queue while not +// queued, projectbluefin/utah#1274 at 074 while the hive tracks it at 085). +// The guard is there so the hive does not start labelling items nobody asked +// about; an item already carrying the hive's stage label is not one, so the +// stage labeler states that fact (writeback.Item.HiveAppliedStage) and the +// gate lets the hive keep its own label current. The fact is read from the +// timeline, and only for a PR the guard would hold. + +// hiveStageFactTTL bounds how long a timeline answer is reused for the same +// stage label set. A label change re-reads at once; the TTL catches a label +// a person removed and re-added under the same name. +const hiveStageFactTTL = 30 * time.Minute + +// hiveStageNow is the clock the memo ages entries by (tests replace it). +var hiveStageNow = time.Now + +// hiveStageFact is one memoised answer: the stage labels it was read for, +// whether the hive applied all of them, and when it was read. +type hiveStageFact struct { + labels string + applied bool + at time.Time +} + +// stageLabelSet is the sorted, comma-joined stage/* labels of labels, "" +// when it carries none. +func stageLabelSet(labels []string) string { + var stage []string + for _, l := range labels { + if l = strings.TrimSpace(l); stagelabels.IsStageLabel(l) { + stage = append(stage, strings.ToLower(l)) + } + } + sort.Strings(stage) + return strings.Join(stage, ",") +} + +// HiveAppliedStageLabels reports whether the item carries at least one +// stage/* label and the newest labeled event of every stage/* label in +// labels was made by one of the hive's own accounts (its App bot, an +// additional hive bot login, or the configured ai_author). A stage label a +// person put on the item, or one with no labeled event in the timeline, +// makes it false: that label is the person's, and the backfill guard keeps +// the hive off it as before. A timeline read that fails reports false and is +// not remembered. +func (c *Client) HiveAppliedStageLabels(ctx context.Context, repo string, number int, labels []string) bool { + set := stageLabelSet(labels) + if c == nil || c.client == nil || set == "" || number <= 0 { + return false + } + key := strings.ToLower(strings.TrimSpace(repo)) + "#" + strconv.Itoa(number) + now := hiveStageNow() + c.hiveStageMu.Lock() + if f, ok := c.hiveStage[key]; ok && f.labels == set && now.Sub(f.at) < hiveStageFactTTL { + c.hiveStageMu.Unlock() + return f.applied + } + c.hiveStageMu.Unlock() + + events, err := c.IssueTimelineSince(ctx, repo, number, time.Time{}) + if err != nil { + return false + } + applied := c.stageLabelsAppliedByHive(strings.Split(set, ","), events) + c.hiveStageMu.Lock() + if c.hiveStage == nil { + c.hiveStage = map[string]hiveStageFact{} + } + c.hiveStage[key] = hiveStageFact{labels: set, applied: applied, at: now} + c.hiveStageMu.Unlock() + return applied +} + +// stageLabelsAppliedByHive reports whether the newest labeled event of each +// label in stage (lower-cased stage/* names) names a hive account. events +// are oldest first, as IssueTimelineSince returns them. +func (c *Client) stageLabelsAppliedByHive(stage []string, events []IssueEvent) bool { + actor := map[string]string{} + for _, ev := range events { + if ev.Event == "labeled" { + actor[strings.ToLower(strings.TrimSpace(ev.Label))] = ev.Actor + } + } + for _, label := range stage { + who, ok := actor[label] + if !ok || !(c.isOwnBotLogin(who) || c.IsHiveAuthorLogin(who)) { + return false + } + } + return len(stage) > 0 +} + +// withHiveAppliedStage returns item with HiveAppliedStage stated when the +// write-back gate's backfill guard would hold a stage write on it and its +// stage labels are the hive's. Any other item is returned as is, without a +// timeline read: a hive-authored PR, one with no stage label, and one the +// guard does not cover are decided as before. +func (c *Client) withHiveAppliedStage(ctx context.Context, repo string, item writeback.Item) writeback.Item { + if item.HiveAuthored || item.HiveAppliedStage || stageLabelSet(item.Labels) == "" { + return item + } + if !c.WritebackGate().BackfillHolds(repo, item) { + return item + } + item.HiveAppliedStage = c.HiveAppliedStageLabels(ctx, repo, item.Number, item.Labels) + return item +} diff --git a/src/pkg/github/stage_label_hive_applied_test.go b/src/pkg/github/stage_label_hive_applied_test.go new file mode 100644 index 0000000000..8ef3c3c420 --- /dev/null +++ b/src/pkg/github/stage_label_hive_applied_test.go @@ -0,0 +1,227 @@ +package github + +import ( + "context" + "encoding/json" + "fmt" + "io" + "log/slog" + "net/http" + "net/http/httptest" + "strings" + "sync" + "testing" + "time" + + "github.com/hivecommons/hive/pkg/writeback" +) + +// A PR older than the backfill cutoff kept whatever stage label the hive +// last put on it: the gate refused the move and the removal alike +// (projectbluefin/utah-packages#1148 sat at stage/100-merge-queue while not +// queued). These tests run the stage labeler through a real gate: a stage +// label the hive applied is moved, one a person applied is left alone, and +// only a PR the guard would hold costs a timeline read. + +const ( + hiveStageRepo = "acme/widgets" + hiveStagePR = 90 + hiveStageOld = "2026-01-15T09:00:00Z" // before hiveStageFirstSeen + hiveStageNew = "2026-07-01T09:00:00Z" // after it +) + +var hiveStageFirstSeen = time.Date(2026, 6, 1, 12, 0, 0, 0, time.UTC) + +// hiveStageServer is acme/widgets with one open PR, #90, carrying labels. +// actor applied its stage label, per the timeline. +type hiveStageServer struct { + mu sync.Mutex + calls []string + labels []string + actor string + createdAt string +} + +func (f *hiveStageServer) ServeHTTP(w http.ResponseWriter, r *http.Request) { + f.mu.Lock() + defer f.mu.Unlock() + w.Header().Set("Content-Type", "application/json") + f.calls = append(f.calls, r.Method+" "+r.URL.Path) + const issue = "/repos/" + hiveStageRepo + "/issues/90" + switch { + case r.Method == "GET" && r.URL.Path == issue: + labels := []any{} + for _, l := range f.labels { + labels = append(labels, map[string]any{"name": l}) + } + _ = json.NewEncoder(w).Encode(map[string]any{ + "number": hiveStagePR, "state": "open", "created_at": f.createdAt, + "updated_at": "2026-11-17T10:00:00Z", "user": map[string]any{"login": "contributor"}, + "labels": labels, "pull_request": map[string]any{"url": "x"}, + }) + case r.Method == "GET" && r.URL.Path == issue+"/timeline": + var events []map[string]any + for _, l := range f.labels { + events = append(events, map[string]any{ + "event": "labeled", "created_at": "2026-11-16T05:18:44Z", + "label": map[string]any{"name": l}, "actor": map[string]any{"login": f.actor}, + }) + } + _ = json.NewEncoder(w).Encode(events) + case r.Method == "POST" && r.URL.Path == issue+"/labels": + var body []string + _ = json.NewDecoder(r.Body).Decode(&body) + f.labels = append(f.labels, body...) + _, _ = io.WriteString(w, `[]`) + case r.Method == "DELETE" && strings.HasPrefix(r.URL.Path, issue+"/labels/"): + gone := strings.TrimPrefix(r.URL.Path, issue+"/labels/") + var kept []string + for _, l := range f.labels { + if l != gone { + kept = append(kept, l) + } + } + f.labels = kept + _, _ = io.WriteString(w, `[]`) + default: + w.WriteHeader(http.StatusNotFound) + _, _ = fmt.Fprintf(w, `{"path":%q}`, r.URL.Path) + } +} + +func (f *hiveStageServer) count(prefix string) int { + f.mu.Lock() + defer f.mu.Unlock() + n := 0 + for _, c := range f.calls { + if strings.HasPrefix(c, prefix) { + n++ + } + } + return n +} + +// hiveStageRig is a client over f with a gate that first saw acme/widgets +// at hiveStageFirstSeen; mode full, so the backfill guard is the only check +// that can refuse a stage label here. +func hiveStageRig(t *testing.T, f *hiveStageServer) (*Client, *writeback.Gate) { + t.Helper() + srv := httptest.NewServer(f) + t.Cleanup(srv.Close) + c := NewClientForTest(srv.URL, "acme", []string{"widgets"}, slog.New(slog.NewTextHandler(io.Discard, nil))) + c.appBotLogin = testBot + gate := writeback.New(writeback.Config{PerRepo: map[string]writeback.RepoOverride{hiveStageRepo: {Mode: writeback.RepoModeFull}}}, writeback.Deps{ + LevelFor: func(string) int { return 6 }, + Now: func() time.Time { return hiveStageFirstSeen }, + }, "") + gate.ObserveRepo(hiveStageRepo) + c.SetWritebackGate(gate) + return c, gate +} + +// moveStage is one stage sync: read #90, add 085, remove 100. +func moveStage(t *testing.T, c *Client) { + t.Helper() + ctx := context.Background() + l := c.StageLabeler() + if _, err := l.Labels(ctx, "acme", "widgets", hiveStagePR); err != nil { + t.Fatal(err) + } + if err := l.AddLabels(ctx, "acme", "widgets", hiveStagePR, []string{"stage/085-needs-decision"}); err != nil { + t.Fatal(err) + } + if err := l.RemoveLabel(ctx, "acme", "widgets", hiveStagePR, "stage/100-merge-queue"); err != nil { + t.Fatal(err) + } +} + +func TestStageLabelerMovesAStageLabelTheHiveAppliedOnAnOldPR(t *testing.T) { + f := &hiveStageServer{labels: []string{"stage/100-merge-queue", "role/trusted"}, actor: testBot, createdAt: hiveStageOld} + c, gate := hiveStageRig(t, f) + moveStage(t, c) + if f.count("POST ") != 1 || f.count("DELETE ") != 1 { + t.Fatalf("calls = %v, want 085 added and 100 removed", f.calls) + } + if held := gate.Recent(); len(held) != 0 { + t.Fatalf("gate held %+v, want nothing held", held) + } + if n := gate.Snapshot().Repos[hiveStageRepo].PreExisting; n != 0 { + t.Fatalf("pre-existing untouched = %d, want 0: the hive wrote to this PR", n) + } +} + +func TestStageLabelerLeavesAPersonsStageLabelOnAnOldPR(t *testing.T) { + f := &hiveStageServer{labels: []string{"stage/100-merge-queue"}, actor: "maintainer", createdAt: hiveStageOld} + c, gate := hiveStageRig(t, f) + moveStage(t, c) + if f.count("POST ") != 0 || f.count("DELETE ") != 0 { + t.Fatalf("calls = %v, want no label write on a person's stage label", f.calls) + } + held := gate.Recent() + if len(held) == 0 || held[0].Reason != writeback.ReasonBackfill { + t.Fatalf("gate held %+v, want the backfill guard's refusal", held) + } +} + +// A PR the guard does not cover is decided as before, with no timeline read; +// on an old PR the answer is read once and reused while its stage labels +// stay the same. +func TestStageLabelerReadsTheTimelineOnlyForAHeldPROnce(t *testing.T) { + newer := &hiveStageServer{labels: []string{"stage/100-merge-queue"}, actor: testBot, createdAt: hiveStageNew} + c, _ := hiveStageRig(t, newer) + moveStage(t, c) + if n := newer.count("GET /repos/acme/widgets/issues/90/timeline"); n != 0 { + t.Fatalf("timeline read %d times for a PR the guard does not cover, want 0", n) + } + if newer.count("POST ") != 1 { + t.Fatalf("calls = %v, want the move to land", newer.calls) + } + + old := &hiveStageServer{labels: []string{"stage/100-merge-queue"}, actor: "maintainer", createdAt: hiveStageOld} + c, _ = hiveStageRig(t, old) + moveStage(t, c) + moveStage(t, c) + if n := old.count("GET /repos/acme/widgets/issues/90/timeline"); n != 1 { + t.Fatalf("timeline read %d times over two syncs with the same labels, want 1", n) + } + // Past the TTL the answer is read again: a person may have removed and + // re-added a label under the same name. + later := time.Now().Add(hiveStageFactTTL + time.Minute) + defer func(prev func() time.Time) { hiveStageNow = prev }(hiveStageNow) + hiveStageNow = func() time.Time { return later } + moveStage(t, c) + if n := old.count("GET /repos/acme/widgets/issues/90/timeline"); n != 2 { + t.Fatalf("timeline read %d times after the TTL, want 2", n) + } +} + +func TestStageLabelsAppliedByHive(t *testing.T) { + c := NewClientForTest("http://unused", "acme", []string{"widgets"}, slog.New(slog.NewTextHandler(io.Discard, nil))) + c.appBotLogin = testBot + ev := func(label, actor string) IssueEvent { return IssueEvent{Event: "labeled", Label: label, Actor: actor} } + cases := []struct { + name string + stage []string + events []IssueEvent + want bool + }{ + {"hive applied the one stage label", []string{"stage/100-merge-queue"}, []IssueEvent{ev("stage/100-merge-queue", testBot)}, true}, + {"a person re-applied it later", []string{"stage/100-merge-queue"}, []IssueEvent{ev("stage/100-merge-queue", testBot), ev("stage/100-merge-queue", "maintainer")}, false}, + {"the hive re-applied a person's label", []string{"stage/100-merge-queue"}, []IssueEvent{ev("stage/100-merge-queue", "maintainer"), ev("stage/100-merge-queue", testBot)}, true}, + {"one of two is a person's", []string{"stage/071-needs-author", "stage/100-merge-queue"}, []IssueEvent{ev("stage/071-needs-author", testBot), ev("stage/100-merge-queue", "maintainer")}, false}, + {"no labeled event for it", []string{"stage/100-merge-queue"}, nil, false}, + {"no stage label", nil, []IssueEvent{ev("stage/100-merge-queue", testBot)}, false}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + if got := c.stageLabelsAppliedByHive(tc.stage, tc.events); got != tc.want { + t.Fatalf("got %v, want %v", got, tc.want) + } + }) + } + if got := stageLabelSet([]string{"role/trusted", "Stage/100-merge-queue", "stage/071-needs-author", "stage/health-x"}); got != "stage/071-needs-author" { + // IsStageLabel is case-sensitive on the prefix, as the stage engine's + // labels are; only ordered stage/NNN-slug labels count. + t.Fatalf("stageLabelSet = %q", got) + } +} diff --git a/src/pkg/github/stage_labeler.go b/src/pkg/github/stage_labeler.go index 131fb73ac8..a9e456c742 100644 --- a/src/pkg/github/stage_labeler.go +++ b/src/pkg/github/stage_labeler.go @@ -53,13 +53,24 @@ func (s *stageLabeler) Labels(ctx context.Context, owner, repo string, number in // the hive did not open is a contributor's and needs the opt-in label // (hivecommons/hive, torch-spyre 2026-10-28). A PR the labeler never read // (no facts) is gated with what it knows: number only. -func (s *stageLabeler) writeAllowed(owner, repo string, number int, preview string) bool { +// +// A PR the backfill guard would hold whose stage labels the hive applied is +// asked with that fact (withHiveAppliedStage), so the hive moves its own +// stage label on an old PR instead of leaving a stage it no longer believes. +// The answer is kept with the item's facts for the writes that follow. +func (s *stageLabeler) writeAllowed(ctx context.Context, owner, repo string, number int, preview string) bool { s.mu.Lock() item, ok := s.facts[number] s.mu.Unlock() if !ok || !item.IsPR { return true } + if stated := s.c.withHiveAppliedStage(ctx, owner+"/"+repo, item); stated.HiveAppliedStage != item.HiveAppliedStage { + item = stated + s.mu.Lock() + s.facts[number] = item + s.mu.Unlock() + } d := s.c.WritebackAllowed(owner+"/"+repo, item, writeback.KindStageLabel, preview) if !d.Allowed { s.mu.Lock() @@ -80,14 +91,14 @@ func (s *stageLabeler) observedAt(number int) string { } func (s *stageLabeler) AddLabels(ctx context.Context, owner, repo string, number int, labels []string) error { - if !s.writeAllowed(owner, repo, number, "add "+strings.Join(labels, ", ")) { + if !s.writeAllowed(ctx, owner, repo, number, "add "+strings.Join(labels, ", ")) { return nil } return s.c.addLabelsObserved(ctx, owner+"/"+repo, number, labels, s.observedAt(number)) // writeback:gated } func (s *stageLabeler) RemoveLabel(ctx context.Context, owner, repo string, number int, label string) error { - if !s.writeAllowed(owner, repo, number, "remove "+label) { + if !s.writeAllowed(ctx, owner, repo, number, "remove "+label) { return nil } return s.c.removeLabelObserved(ctx, owner+"/"+repo, number, label, s.observedAt(number)) // writeback:gated diff --git a/src/pkg/writeback/gate.go b/src/pkg/writeback/gate.go index 571d44c12c..40af080e6a 100644 --- a/src/pkg/writeback/gate.go +++ b/src/pkg/writeback/gate.go @@ -55,6 +55,14 @@ type Item struct { // label requirement (ReasonHiveAppliedPark). No other kind reads it, // and no other caller of that kind sets it. HiveAppliedPark bool + // HiveAppliedStage is true when the caller has established that the + // item carries at least one stage/* label and that the newest labeled + // event of every stage/* label it carries was made by one of the hive's + // own accounts. Set only by the stage labeler; with KindStageLabel it + // lifts the backfill guard and nothing else (ReasonHiveAppliedStage): + // the opt-in label, the level and every other check still apply. No + // other kind reads it. + HiveAppliedStage bool // Labels is the item's current label set. Labels []string // CreatedAt is the item's creation time; the backfill guard compares it @@ -117,6 +125,18 @@ const ( // the repo mode, project membership, own_only and the kind's minimum // level still do. ReasonHiveAppliedPark = "hive-applied-park" + // ReasonHiveAppliedStage allows a stage-label write (KindStageLabel with + // Item.HiveAppliedStage) on an item older than the backfill cutoff whose + // stage labels the hive itself applied. The guard keeps the hive from + // starting to label items nobody asked about; this item already carries + // the hive's stage label, and leaving it at a stage the hive no longer + // believes (stage/100-merge-queue on a PR that is not queued) misleads + // every maintainer who reads it. Moving or removing its own label is + // upkeep of the hive's state, so the backfill guard does not apply. The + // opt-in label, a pause, the repo mode, project membership, own_only and + // the kind's minimum level still do: the write is allowed exactly when + // it would be on an item the guard does not cover. + ReasonHiveAppliedStage = "hive-applied-stage" ) // RepoPauseInfo is the provenance of an operator pause, as config records @@ -503,6 +523,28 @@ func (g *Gate) decideLocked(repo string, item Item, kind Kind) Decision { // The park re-check's note on a park the hive applied is the same case: // the hive's label is already on the item. hivePark := kind == KindNeedsDecisionComment && item.HiveAppliedPark + // A stage label the hive applied is the hive's state, not a first + // write: the backfill guard is the one check the fact lifts. The item + // is decided as one the guard does not cover (CreatedAt cleared), so + // the opt-in label and the level below answer exactly as they would + // for a newer item, and an allow says why the guard did not hold it. + if kind == KindStageLabel && item.HiveAppliedStage && !optedIn { + if held, cut := g.backfillHoldsLocked(repo, item); held { + rest := item + rest.HiveAppliedStage = false + rest.CreatedAt = time.Time{} + d := g.decideLocked(repo, rest, kind) + if d.Allowed { + why := d.Reason + if d.Detail != "" { + why += ": " + d.Detail + } + d.Detail = fmt.Sprintf("the hive applied the stage label on #%d itself, so the backfill guard (cutoff %s) does not apply; then %s", item.Number, cut.Format(time.RFC3339), why) + d.Reason = ReasonHiveAppliedStage + } + return d + } + } if !optedIn && !hiveBlock && !hivePark { if backfilled, cut := g.backfillBlockedLocked(repo, item); backfilled { return Decision{Reason: ReasonBackfill, Detail: fmt.Sprintf("#%d was created %s, before hive could write to %s (%s); writeback.unsolicited.backfill is off", item.Number, item.CreatedAt.UTC().Format(time.RFC3339), repo, cut.Format(time.RFC3339))} @@ -619,15 +661,44 @@ func (g *Gate) levelCheckLocked(repo string, _ Item, kind Kind, ok Decision) Dec return ok } -func (g *Gate) backfillBlockedLocked(repo string, item Item) (bool, time.Time) { +// BackfillHolds reports whether the backfill guard would refuse an +// unsolicited write on item: backfill is off, item carries no opt-in label +// and predates the repo's cutoff. Unlike a decision it records nothing, so +// asking does not count item among the pre-existing items left untouched. +// The stage labeler asks it before reading an item's timeline, so only a +// PR the guard would hold costs that read. +func (g *Gate) BackfillHolds(repo string, item Item) bool { + if g == nil { + return false + } + g.mu.Lock() + defer g.mu.Unlock() + if g.optedInLocked(repo, item) { + return false + } + held, _ := g.backfillHoldsLocked(repo, item) + return held +} + +// backfillHoldsLocked is the backfill guard's test, without recording the +// item as pre-existing. +func (g *Gate) backfillHoldsLocked(repo string, item Item) (bool, time.Time) { if g.cfgLocked().BackfillEnabled() || item.CreatedAt.IsZero() { return false, time.Time{} } - rec := g.recordLocked(repo) - cut := rec.backfillCutoff() + cut := g.recordLocked(repo).backfillCutoff() if cut.IsZero() || !item.CreatedAt.Before(cut) { return false, cut } + return true, cut +} + +func (g *Gate) backfillBlockedLocked(repo string, item Item) (bool, time.Time) { + held, cut := g.backfillHoldsLocked(repo, item) + if !held { + return false, cut + } + rec := g.recordLocked(repo) if rec.PreExisting == nil { rec.PreExisting = map[int]bool{} } diff --git a/src/pkg/writeback/hive_applied_stage_test.go b/src/pkg/writeback/hive_applied_stage_test.go new file mode 100644 index 0000000000..62c7f130bd --- /dev/null +++ b/src/pkg/writeback/hive_applied_stage_test.go @@ -0,0 +1,146 @@ +package writeback + +import ( + "testing" + "time" +) + +// The stage labeler states when an item's stage labels are the hive's own +// (Item.HiveAppliedStage). For stage_label that lifts the backfill guard and +// nothing else: the hive keeps its own label current on an old PR, while a +// first stage label on an old item, every other kind, and every other check +// answer as before. + +var ( + // oldPR predates the gate's first sight of org/repo (t0); newPR does not. + oldPR = Item{Number: 60, IsPR: true, Author: "contributor", Labels: []string{"stage/100-merge-queue"}, CreatedAt: t0.Add(-48 * time.Hour)} + newPR = Item{Number: 61, IsPR: true, Author: "contributor", Labels: []string{"stage/100-merge-queue"}, CreatedAt: t0.Add(time.Hour)} +) + +// hiveStaged is it with the labeler's finding that the hive applied its +// stage labels. +func hiveStaged(it Item) Item { + it.HiveAppliedStage = true + return it +} + +func TestHiveAppliedStageLiftsOnlyTheBackfillGuard(t *testing.T) { + labelOff := Config{Kinds: map[string]KindPolicyOverride{"stage_label": {RequireLabel: boolp(false)}}} + full := Config{PerRepo: map[string]RepoOverride{"org/repo": {Mode: RepoModeFull}}} + cases := []struct { + name string + cfg Config + item Item + kind Kind + allow bool + reason string + }{ + // require_label off: the level alone decides once the guard is lifted. + {"old PR, hive stage label", labelOff, hiveStaged(oldPR), KindStageLabel, true, ReasonHiveAppliedStage}, + {"old PR, fact not stated", labelOff, oldPR, KindStageLabel, false, ReasonBackfill}, + {"old PR, a comment kind ignores the fact", labelOff, hiveStaged(oldPR), KindGateComment, false, ReasonBackfill}, + {"old PR, needs_decision_comment ignores the fact", labelOff, hiveStaged(oldPR), KindNeedsDecisionComment, false, ReasonBackfill}, + {"new PR, hive stage label: decided as before", labelOff, hiveStaged(newPR), KindStageLabel, true, ReasonLevel}, + {"new PR, fact not stated", labelOff, newPR, KindStageLabel, true, ReasonLevel}, + + // The default policy still wants the opt-in label after the guard. + {"old PR, hive stage label, no opt-in label", Config{}, hiveStaged(oldPR), KindStageLabel, false, ReasonNeedsLabel}, + {"old PR, fact not stated, default policy", Config{}, oldPR, KindStageLabel, false, ReasonBackfill}, + + // Mode full allows any write the guard does not hold. + {"old PR, hive stage label, mode full", full, hiveStaged(oldPR), KindStageLabel, true, ReasonHiveAppliedStage}, + {"old PR, fact not stated, mode full", full, oldPR, KindStageLabel, false, ReasonBackfill}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + g, _ := newGate(t, tc.cfg, 6) + d := g.Allowed("org/repo", tc.item, tc.kind) + if d.Allowed != tc.allow || d.Reason != tc.reason { + t.Fatalf("got %+v, want allow=%v reason=%s", d, tc.allow, tc.reason) + } + }) + } +} + +// The fact lifts the guard and no other check: a pause, the repo mode, +// project membership, own_only and the kind's minimum level refuse the label +// write as they refuse any other. +func TestHiveAppliedStageStillHeldByPauseModeProjectOwnOnlyAndLevel(t *testing.T) { + item := hiveStaged(oldPR) + base := map[string]KindPolicyOverride{"stage_label": {RequireLabel: boolp(false)}} + mode := func(m RepoMode) Config { + return Config{Kinds: base, PerRepo: map[string]RepoOverride{"org/repo": {Mode: m}}} + } + cases := []struct { + name string + cfg Config + level int + paused bool + listed bool + allow bool + reason string + }{ + {"paused repo", Config{Kinds: base}, 6, true, true, false, ReasonRepoPaused}, + {"repo mode off", mode(RepoModeOff), 6, false, true, false, ReasonRepoOff}, + {"repo mode issues-only", mode(RepoModeIssuesOnly), 6, false, true, false, ReasonRepoIssues}, + {"repo mode labels-only", mode(RepoModeLabelsOnly), 6, false, true, true, ReasonHiveAppliedStage}, + {"repo not in the project", Config{Kinds: base}, 6, false, false, false, ReasonRepoNotListed}, + {"own_only set by an operator", Config{Kinds: map[string]KindPolicyOverride{"stage_label": {RequireLabel: boolp(false), OwnOnly: boolp(true)}}}, 6, false, true, false, ReasonOwnOnly}, + {"level unset", Config{Kinds: base}, 0, false, true, false, ReasonLevelUnknown}, + {"below the kind's floor", Config{Kinds: base}, 4, false, true, false, ReasonBelowLevel}, + {"at the kind's floor", Config{Kinds: base}, 5, false, true, true, ReasonHiveAppliedStage}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + g := New(tc.cfg, Deps{ + LevelFor: func(string) int { return tc.level }, + RepoListed: func(string) bool { return tc.listed }, + RepoPause: func(string) (RepoPauseInfo, bool) { return RepoPauseInfo{By: "owner"}, tc.paused }, + Now: func() time.Time { return t0 }, + }, "") + g.ObserveRepo("org/repo") + d := g.Allowed("org/repo", item, KindStageLabel) + if d.Allowed != tc.allow || d.Reason != tc.reason { + t.Fatalf("got %+v, want allow=%v reason=%s", d, tc.allow, tc.reason) + } + }) + } +} + +// A stage write the fact let through is not one of the "pre-existing items +// left untouched" the backfill banner counts; a refused one still is. Asking +// BackfillHolds records nothing. +func TestHiveAppliedStageDoesNotCountAsBackfillSkip(t *testing.T) { + cfg := Config{Kinds: map[string]KindPolicyOverride{"stage_label": {RequireLabel: boolp(false)}}} + g, _ := newGate(t, cfg, 6) + if !g.BackfillHolds("org/repo", oldPR) || g.BackfillHolds("org/repo", newPR) { + t.Fatal("BackfillHolds: want true for the old PR only") + } + opted := oldPR + opted.Labels = append([]string{"hive-review"}, oldPR.Labels...) + if g.BackfillHolds("org/repo", opted) { + t.Fatal("BackfillHolds on an opted-in item: the guard never applies to it") + } + if n := g.Snapshot().Repos["org/repo"].PreExisting; n != 0 { + t.Fatalf("pre-existing untouched = %d after BackfillHolds, want 0", n) + } + if d := g.Allowed("org/repo", hiveStaged(oldPR), KindStageLabel); !d.Allowed || d.Reason != ReasonHiveAppliedStage { + t.Fatalf("hive stage label on an old PR = %+v, want allowed", d) + } + if n := g.Snapshot().Repos["org/repo"].PreExisting; n != 0 { + t.Fatalf("pre-existing untouched = %d after an allowed stage move, want 0", n) + } + if d := g.Allowed("org/repo", oldPR, KindStageLabel); d.Allowed || d.Reason != ReasonBackfill { + t.Fatalf("fact not stated = %+v, want refused by backfill", d) + } + if n := g.Snapshot().Repos["org/repo"].PreExisting; n != 1 { + t.Fatalf("pre-existing untouched = %d after a backfill refusal, want 1", n) + } +} + +func TestBackfillHoldsNilGate(t *testing.T) { + var g *Gate + if g.BackfillHolds("org/repo", oldPR) { + t.Fatal("a nil gate holds nothing") + } +} diff --git a/src/pkg/writeback/kinds.go b/src/pkg/writeback/kinds.go index bab1a9ab45..494f864cb1 100644 --- a/src/pkg/writeback/kinds.go +++ b/src/pkg/writeback/kinds.go @@ -38,7 +38,10 @@ const ( // merge-from-base push that keeps a held PR mergeable. KindHoldGateNotice Kind = "hold_gate_notice" // KindStageLabel is every stage/*, role/* and hive-owned ownership label - // the stage engine writes on an item. + // the stage engine writes on an item. The stage labeler states when the + // item's stage labels are the hive's own (Item.HiveAppliedStage); the + // gate then skips the backfill guard for that item and nothing else + // (ReasonHiveAppliedStage). Every other caller is gated as before. KindStageLabel Kind = "stage_label" // KindNeedsDecisionComment is the `hive:stage-needs-decision` / 085 // park comment and label on an item a person must decide on. The park From ff0be490f424a9cfd69600c73c54430450c480af Mon Sep 17 00:00:00 2001 From: Danathar <6772335+Danathar@users.noreply.github.com> Date: Tue, 17 Nov 2026 17:33:43 -0500 Subject: [PATCH 2/2] docs: re-cite RankActionableIssues after the client.go insert The five lines this branch adds to client.go moved RankActionableIssues from 5588 to 5593; scale-envelope.md now cites 5593-5603 so the docs citation check finds the AgeMinutes anchor again. Signed-off-by: Danathar <6772335+Danathar@users.noreply.github.com> Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1 --- 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 093215d6f4..1f9da47b4e 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:5588-5598`, descending `AgeMinutes` within each tier). + (`RankActionableIssues`, `src/pkg/github/client.go:5593-5603`, descending `AgeMinutes` within each tier). - PRs are sorted by **review class then oldest-first within class** (`SortPullRequestsForReview`, `src/pkg/github/review_priority.go:334`; fixes → refactors/docs → tests).