Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/fixed-backfill-hive-applied-stage.md
Original file line number Diff line number Diff line change
@@ -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.
15 changes: 15 additions & 0 deletions src/docs/operator-reference/sweeps-and-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -677,6 +677,21 @@ one line — `writeback: skipped N pre-existing items on <repo> (backfill
off)` — and the dashboard shows "hive can now write to `<repo>`; 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
Expand Down
2 changes: 1 addition & 1 deletion src/docs/scale-envelope.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
10 changes: 6 additions & 4 deletions src/pkg/github/automerge/automerge_contributor_adopt.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
}
Expand Down
57 changes: 54 additions & 3 deletions src/pkg/github/automerge/automerge_stage_move_suppressed_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
Expand All @@ -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)
}
})
Expand All @@ -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)
}
}
Expand Down Expand Up @@ -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)
}
}
26 changes: 26 additions & 0 deletions src/pkg/github/automerge/automerge_writeback.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
package automerge

import (
"context"

"github.com/hivecommons/hive/pkg/writeback"
)

Expand Down Expand Up @@ -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
}
5 changes: 5 additions & 0 deletions src/pkg/github/client.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)) {
Expand Down
124 changes: 124 additions & 0 deletions src/pkg/github/stage_label_hive_applied.go
Original file line number Diff line number Diff line change
@@ -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
}
Loading
Loading