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-18434-model-stage-label-flap.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Workflow-model repositories no longer flap `stage/020-claimed` every cycle: the in-progress sweep leaves a stage label the bound model derives for the issue (TechDocs "Accepted") in place and does not treat it as a claim, and out-of-cycle stage facts derive through the same bound model as the sweeps (#18434).
6 changes: 6 additions & 0 deletions src/cmd/hive/github_client_config.go
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,12 @@ 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 }))
// The bound workflow model lookup the stage engine derives through: the
// in-progress sweep and the out-of-cycle stage facts must agree with the
// sweeps on a model-bound repository (hivecommons/hive#18434,
// stage_model_owned.go). StageReconciler also installs it, but only once
// a sweep builds the reconciler for this client.
client.SetStageWorkflowFor(stageEngineOptions(b.cfg, b.logger).WorkflowFor)
// 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).
Expand Down
3 changes: 3 additions & 0 deletions src/pkg/github/client.go
Original file line number Diff line number Diff line change
Expand Up @@ -569,6 +569,9 @@ type Client struct {
stageEngineMu sync.Mutex
stageWriter *stageWriter
stageEngines map[*stagelabels.Store]stageengine.Reconciler
// stageWorkflow is the per-repository workflow model lookup the stage
// engine derives through (stage_model_owned.go, hivecommons/hive#18434).
stageWorkflow atomic.Pointer[stageWorkflowLookup]
// baseRefresh is the decision carry's memo (pr_decision_base_refresh.go).
baseRefreshOnce sync.Once
baseRefresh *BaseRefreshChecker
Expand Down
32 changes: 31 additions & 1 deletion src/pkg/github/issue_inprogress.go
Original file line number Diff line number Diff line change
Expand Up @@ -311,8 +311,16 @@ func SweepInProgressIssues(ctx context.Context, client *Client, result *Actionab
kept = append(kept, issue)
continue
}
// The bound workflow model may derive this very stage label for the
// issue's state (TechDocs Accepted is number 20): then it is the
// model's, not a claim. Stripping it here only had the stage sync
// put it back two seconds later, every cycle (hivecommons/hive#18434).
// A live start mark still withholds the issue; the label stays.
modelOwned := client.modelOwnsInProgressTrigger(issue)
if issueHasPREvidence(issue) {
client.removeInProgressLabel(ctx, &issue, "pr evidence", logger)
if !modelOwned {
client.removeInProgressLabel(ctx, &issue, "pr evidence", logger)
}
kept = append(kept, issue)
continue
}
Expand All @@ -337,6 +345,10 @@ func SweepInProgressIssues(ctx context.Context, client *Client, result *Actionab
"repo", issue.Repo, "issue", issue.Number, "agent", claim.Identity,
"started_at", claim.StartedAt, "expires_at", claim.ExpiresAt)
}
case modelOwned:
// No live claim and the label is the model's state: the issue
// is not claimed, and the label is not ours to take off.
kept = append(kept, issue)
default:
client.removeInProgressLabel(ctx, &issue, "start mark lapsed", logger)
kept = append(kept, issue)
Expand All @@ -351,6 +363,24 @@ func SweepInProgressIssues(ctx context.Context, client *Client, result *Actionab
return withheld
}

// modelOwnsInProgressTrigger reports whether every trigger label the issue
// carries is the stage label its bound workflow model derives (see
// Client.modelOwnsStageLabel). A retired trigger (hive/in-progress) is never
// the model's, so an issue still wearing one is swept as before.
func (c *Client) modelOwnsInProgressTrigger(issue Issue) bool {
owned := false
for _, l := range inProgressTriggerLabels {
if !issueHasLabel(issue.Labels, l) {
continue
}
if !c.modelOwnsStageLabel(issue, l) {
return false
}
owned = true
}
return owned
}

func startedLabel(claim issueclaim.Claim) string {
if claim.StartedAt.IsZero() {
return "an unrecorded time"
Expand Down
7 changes: 6 additions & 1 deletion src/pkg/github/issue_stage_labels.go
Original file line number Diff line number Diff line change
Expand Up @@ -392,6 +392,11 @@ func forgeIssueLabels(labels []string, claim *IssueClaimContext) []string {
return removeIssueLabel(slices.Clone(labels), CoveredByPRLabel)
}

// issueStageInputFrom is the stage input for one actionable issue.
func issueStageInputFrom(issue Issue) IssueStageInput {
return IssueStageInput{Repo: issue.Repo, Number: issue.Number, Labels: forgeIssueLabels(issue.Labels, issue.ClaimContext), Title: issue.Title, ClaimKind: issue.ClaimKind, ClaimedBy: issue.ClaimedBy, PRStarted: issue.ClaimPRStarted, Claim: issue.ClaimContext, Children: issue.Children, AuthorKind: issueAuthorKind(issue), DelegatesWork: hasUnfinishedDelegatedWork(issue.Body), SpekUmbrella: spekmarker.IsUmbrella(issue.Body), UpdatedAt: issue.UpdatedAt, Assignees: issue.Assignees}
}

// IssueStageInputs flattens an enumeration result into one row per open
// issue the cycle saw, actionable items first, then every work-detail row.
func IssueStageInputs(result *ActionableResult) []IssueStageInput {
Expand All @@ -400,7 +405,7 @@ func IssueStageInputs(result *ActionableResult) []IssueStageInput {
}
var out []IssueStageInput
for _, issue := range result.Issues.Items {
out = append(out, IssueStageInput{Repo: issue.Repo, Number: issue.Number, Labels: forgeIssueLabels(issue.Labels, issue.ClaimContext), Title: issue.Title, ClaimKind: issue.ClaimKind, ClaimedBy: issue.ClaimedBy, PRStarted: issue.ClaimPRStarted, Claim: issue.ClaimContext, Children: issue.Children, AuthorKind: issueAuthorKind(issue), DelegatesWork: hasUnfinishedDelegatedWork(issue.Body), SpekUmbrella: spekmarker.IsUmbrella(issue.Body), UpdatedAt: issue.UpdatedAt, Assignees: issue.Assignees})
out = append(out, issueStageInputFrom(issue))
}
// Held issues leave the pipeline at enumeration (Hold list, no
// work-detail row). They still have to be walked so a stage label
Expand Down
4 changes: 4 additions & 0 deletions src/pkg/github/stage_facts_sink.go
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,10 @@ func (c *Client) defaultStageFactSink() stageengine.FactSink {
Issue: IssueDeriver(),
PR: stageengine.PRDeriver(),
Logger: c.logger,
// Derive through the repository's bound workflow model, as the
// sweeps do: a fact derived built-in on a model-bound repository
// would write a stage the next sweep reverts (hivecommons/hive#18434).
WorkflowFor: c.stageWorkflowFor,
// Shares the process counters with the sweeps' reconciler so
// /metrics and /api/status count fact-driven writes too.
Metrics: stageengine.DefaultCounters(),
Expand Down
82 changes: 82 additions & 0 deletions src/pkg/github/stage_model_owned.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
package github

import (
"github.com/hivecommons/hive/pkg/stageengine"
"github.com/hivecommons/hive/pkg/stagelabels"
"github.com/hivecommons/hive/pkg/workflowmodel"
)

// Workflow-model stage ownership (hivecommons/hive#18434).
//
// A repository bound to a workflow model derives its stage through the
// model (stageengine.DeriveForRepo). A model state reuses the built-in stage
// label for its lifecycle number, so the TechDocs "Accepted" state (number
// 20: waiting on the reviewer to delegate the drafter) wears
// stage/020-claimed although no agent holds a claim. The in-progress sweep
// read that label as a claim, found no hive:claim marker, and stripped it;
// the stage sync two seconds later derived the model state again and put it
// back. cncf/techdocs#395 flapped every enumeration cycle for a day and a
// half.
//
// Two writers now agree: the in-progress sweep leaves a stage label the
// bound model derives for the issue alone (and does not withhold the issue,
// since a model state is not a claim), and the out-of-cycle FactSink derives
// through the same per-repository model lookup as the sweeps.

// stageWorkflowLookup is the per-repository model lookup, held behind an
// atomic pointer because the sweeps read it while boot installs it.
type stageWorkflowLookup struct {
fn func(owner, repo string) *workflowmodel.Profile
}

// SetStageWorkflowFor installs the per-repository workflow model lookup the
// stage engine uses (stageengine.Options.WorkflowFor). StageReconciler
// installs it from the options it is first built with, so cmd/hive's boot
// wiring needs nothing extra; tests call it directly. Nil clears it.
func (c *Client) SetStageWorkflowFor(fn func(owner, repo string) *workflowmodel.Profile) {
if c == nil {
return
}
if fn == nil {
c.stageWorkflow.Store(nil)
return
}
c.stageWorkflow.Store(&stageWorkflowLookup{fn: fn})
}

// stageWorkflowFor resolves the workflow model bound to owner/repo, or nil
// when none is installed or the repository is unbound.
func (c *Client) stageWorkflowFor(owner, repo string) *workflowmodel.Profile {
if c == nil {
return nil
}
l := c.stageWorkflow.Load()
if l == nil || l.fn == nil {
return nil
}
return l.fn(owner, repo)
}

// modelOwnsStageLabel reports whether the workflow model bound to the
// issue's repository derives a state for the issue whose stage label is
// label. Such a label is the model's state, not a claim: the in-progress
// sweep must neither strip it nor treat the issue as claimed. The built-in
// hive-default model never owns a label (it is the built-in derivation).
func (c *Client) modelOwnsStageLabel(issue Issue, label string) bool {
owner, name := c.splitRepo(issue.Repo)
p := c.stageWorkflowFor(owner, name)
if p == nil || p.Name == hiveDefaultWorkflowName {
return false
}
f := issueFactsFrom(issueStageInputFrom(issue), func(string, int) stagelabels.Stage { return stagelabels.None })
f.Ref.Owner, f.Ref.Repo = owner, name
d := stageengine.DeriveFromModel(p, stagelabels.IssueItem).Derive(f)
if d.Abstain || d.ModelState == "" || d.Stage == stagelabels.None {
return false
}
return d.Stage.Label() == label
}

// hiveDefaultWorkflowName is the built-in model's name
// (workflowmodel.Default); binding it changes nothing about derivation.
const hiveDefaultWorkflowName = "hive-default"
126 changes: 126 additions & 0 deletions src/pkg/github/stage_model_owned_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
package github

import (
"context"
"encoding/json"
"io"
"log/slog"
"os"
"testing"
"time"

"github.com/hivecommons/hive/pkg/stageengine"
"github.com/hivecommons/hive/pkg/stageengine/stageenginetest"
"github.com/hivecommons/hive/pkg/stagelabels"
"github.com/hivecommons/hive/pkg/workflowmodel"
)

// modelOwnedCycles is how many enumeration cycles the flap regression test
// replays: enough for a strip-then-restore loop to show twice.
const modelOwnedCycles = 4

func techdocsModelForStage(t *testing.T) *workflowmodel.Profile {
t.Helper()
b, err := os.ReadFile("../workflowmodel/testdata/models/techdocs.json")
if err != nil {
t.Fatal(err)
}
var m workflowmodel.Model
if err := json.Unmarshal(b, &m); err != nil {
t.Fatal(err)
}
p, diags, err := workflowmodel.Compile(&m)
if err != nil {
t.Fatalf("%v %+v", err, diags)
}
return p
}

// hivecommons/hive#18434: on a repository bound to a workflow model whose
// state derives stage/020-claimed (TechDocs "accepted"), the in-progress
// sweep stripped the label for want of a start mark and the stage sync put
// it back, every cycle. Replaying sweep + stage reconcile must converge:
// one add on the first cycle, then no add or remove at all, and the issue
// is never withheld as claimed.
func TestModelOwnedStageLabel_ReconcileIsIdempotent(t *testing.T) {
p := techdocsModelForStage(t)
lookup := func(owner, repo string) *workflowmodel.Profile { return p }

server, removed := sweepServer(t, []string{"a human comment, no claim marker"})
c := newTestClient(t, server, "acme", []string{"widgets"})
enableInProgress(c, "hive-a", 2*time.Hour)
c.SetStageWorkflowFor(lookup)

ref := stageengine.Ref{Owner: "acme", Repo: "widgets", Number: 7, Kind: stagelabels.IssueItem}
w := stageenginetest.NewWriter()
w.Seed(ref, "techdocs/request", "techdocs/accepted")
r := stageengine.New(stageengine.Options{
Mode: stageengine.ModeEnforce,
Store: stagelabels.NewStore("", nil),
Writer: w,
WorkflowFor: lookup,
Logger: slog.New(slog.NewTextHandler(io.Discard, nil)),
})

for cycle := 0; cycle < modelOwnedCycles; cycle++ {
issue := claimIssue()
issue.Labels = w.LabelsOf(ref)
result := &ActionableResult{Issues: IssueResultFromItems([]Issue{issue})}
if withheld := SweepInProgressIssues(context.Background(), c, result, inProgressNow, nil); withheld != 0 {
t.Fatalf("cycle %d: a model state is not a claim, withheld = %d", cycle, withheld)
}
if len(result.Issues.Items) != 1 {
t.Fatalf("cycle %d: issue must stay in the actionable set, got %+v", cycle, result.Issues.Items)
}
if len(*removed) != 0 {
t.Fatalf("cycle %d: in-progress sweep stripped the model's stage label: %v", cycle, *removed)
}
f := issueFactsFrom(issueStageInputFrom(result.Issues.Items[0]), func(string, int) stagelabels.Stage { return stagelabels.None })
f.Ref = ref
tr, err := r.Reconcile(context.Background(), f)
if err != nil {
t.Fatalf("cycle %d: reconcile: %v", cycle, err)
}
if tr.To != stagelabels.Claimed {
t.Fatalf("cycle %d: model state accepted derives %s, want %s", cycle, tr.To, stagelabels.Claimed)
}
if cycle > 0 && (len(tr.Outcome.Added) > 0 || len(tr.Outcome.Removed) > 0) {
t.Fatalf("cycle %d: label churn: added %v removed %v", cycle, tr.Outcome.Added, tr.Outcome.Removed)
}
}
if !issueHasLabel(w.LabelsOf(ref), stagelabels.Claimed.Label()) {
t.Fatalf("labels = %v, want the model's stage label kept", w.LabelsOf(ref))
}
}

// Off the model (no binding, or the issue is in a state whose label is not
// the trigger), the sweep clears a stage/020-claimed with no live mark
// exactly as before.
func TestModelOwnedStageLabel_UnboundOrOtherStateStillClears(t *testing.T) {
p := techdocsModelForStage(t)
cases := []struct {
name string
lookup func(owner, repo string) *workflowmodel.Profile
labels []string
}{
{"unbound", func(string, string) *workflowmodel.Profile { return nil }, []string{"techdocs/accepted", InProgressLabel}},
{"model state is not claimed", func(string, string) *workflowmodel.Profile { return p }, []string{"techdocs/request", stagelabels.Claimed.Label()}},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
server, removed := sweepServer(t, []string{"just a human comment"})
c := newTestClient(t, server, "acme", []string{"widgets"})
enableInProgress(c, "hive-a", 2*time.Hour)
c.SetStageWorkflowFor(tc.lookup)
issue := claimIssue()
issue.Labels = tc.labels
result := &ActionableResult{Issues: IssueResultFromItems([]Issue{issue})}
if withheld := SweepInProgressIssues(context.Background(), c, result, inProgressNow, nil); withheld != 0 {
t.Fatalf("withheld = %d, want 0", withheld)
}
if len(*removed) != 1 {
t.Fatalf("expected the lapsed label removed once, got %v", *removed)
}
})
}
}
5 changes: 5 additions & 0 deletions src/pkg/github/stage_writer.go
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,11 @@ func (c *Client) StageReconciler(store *stagelabels.Store, opts *stageengine.Opt
if o.Logger == nil && logger != nil {
o.Logger = logger
}
if o.WorkflowFor != nil {
// The in-progress sweep and the FactSink must derive through the
// same bound model as the sweeps (hivecommons/hive#18434).
c.SetStageWorkflowFor(o.WorkflowFor)
}
r := stageengine.New(o)
if c.stageEngines == nil {
c.stageEngines = map[*stagelabels.Store]stageengine.Reconciler{}
Expand Down
Loading