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/changed-16271-attention-budget-wired.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The per-recipient attention budget (`github.attention.recipient_budget`, still `0` = off) and opt-in digest (`github.attention.digest_recipients`) now load from the `github.attention` block and gate the episode ledger's live first pings and reminders: over-budget asks stay open and listed (status card, attention queue, digest) instead of being posted, and security, required-review, protocol-command and hold asks are never budgeted ([#16271](https://github.com/hivecommons/hive/issues/16271)).
7 changes: 6 additions & 1 deletion src/docs/attention-episodes.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ github:
hivecommons/hive: hosted-hive-id
flap_window: 12h
reminder_interval: 24h
recipient_budget: 0 # off; see notifications.md
digest_recipients: []
```

Keys must be fully qualified repositories. Exactly one deployment may own the
Expand All @@ -29,7 +31,10 @@ Unknown-owner uncertain attempts remain visible and are not automatically retrie

Unset/empty `admitter` means this new path does nothing, without opening a ledger
or changing today's quiet-mode delivery. The default flap window is 12 hours.
There is no per-recipient budget in this layer (#16271). With
Every first ping and reminder is admitted through the per-recipient attention
budget (`recipient_budget`, off by default, #16271); see
[Per-recipient attention budget](notifications.md#per-recipient-attention-budget-opt-in-off-by-default).
With
`github.notifications.attention_pilot` on, `reminder_interval` (default `24h`)
bounds reminders to one per unresolved episode per interval; see
[Attention section, tracking issue and reminders](notifications.md#attention-section-tracking-issue-and-reminders).
Expand Down
24 changes: 17 additions & 7 deletions src/docs/notifications.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,15 +147,25 @@ items, and never drops an ask that goes over the cap
| `github.attention.digest_recipients` | empty | GitHub logins (case-insensitive, optional `@`) that opted into the digest. |

These keys live in the `github.attention` block owned by the condition-episode
ledger ([#16267](https://github.com/hivecommons/hive/issues/16267)); the budget
takes effect once the ledger routes its non-urgent writes through it.
ledger ([#16267](https://github.com/hivecommons/hive/issues/16267)), which
admits every non-urgent write through the budget: the ledger's first ping for
a newly actionable episode (`Store.Report`) and every attention-pilot reminder
(`SweepAttentionQueue`). The budget is seeded from the ledger's delivered
history (`paged_to`/`paged_at` and the last reminder) when the ledger opens, so
the rolling window survives restarts. An over-budget ask is never dropped: its
episode stays open and would-notify, is marked `overflowed` in the ledger,
stays in the repo's attention queue issue, and is posted on a later pass once
the recipient's budget frees up (or cleared when it is acknowledged, snoozed
or resolved). Producers mark exempt asks with `Observation.Class`
(`security`, `required_review`, `protocol_command`, `hold`); an unset class is
an ordinary non-urgent ping.

- **Off (shadow mode).** With `recipient_budget: 0` every write is delivered
exactly as before. The budget still counts, per recipient, how many writes
would have overflowed a candidate cap of 5 (`ShadowBudget`) and reports
`delivered`, `exempt`, `overflowed` and `would_overflow` per login in the
`attention budget:` log line, so an operator can choose N from evidence
before enabling it.
`attention budget:` log line (emitted on every attention-queue sweep), so an
operator can choose N from evidence before enabling it.
- **Enabled, recipient opted into the digest.** The (N+1)th non-urgent ping or
reminder in the window is not posted. It stays an open, overflowed ask: it is
listed in the item's status card (`attention-overflow` section), in the
Expand All @@ -164,9 +174,9 @@ takes effect once the ledger routes its non-urgent writes through it.
actionable asks are always posted; only reminders over the cap are deferred
(and remain visible in the status card and action queue).
- **Digest.** One comment per recipient per repo, identified by
`<!-- hive:attention-digest recipient=<login> -->`, created once through the
existing marker-comment upsert and edited in place afterwards (edits notify
nobody). It serves as the reminder for the asks it lists. No external
`<!-- hive:attention-digest recipient=<login> -->`, posted on the repo's
attention queue issue, created once through the existing marker-comment
upsert and edited in place afterwards (edits notify nobody). It serves as the reminder for the asks it lists. No external
service is involved.
- **Never budgeted.** Materially new security risk or imminent destructive
action, mandatory/required reviews, machine-consumed protocol commands, and
Expand Down
1 change: 1 addition & 0 deletions src/internal/settingsparity/settingsparity.go
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ func ConfigLeaves(repoRoot string) ([]Leaf, error) {
filepath.Join("pkg", "dashboard", "theme"),
filepath.Join("pkg", "writeback"),
filepath.Join("pkg", "attention"),
filepath.Join("pkg", "attentionbudget"),
} {
if err := c.collect(fset, repoRoot, rel); err != nil {
return nil, err
Expand Down
2 changes: 1 addition & 1 deletion src/internal/settingsparity/settingsparity_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -170,7 +170,7 @@ func TestConfigLeavesRealRepoEnumeratesAttention(t *testing.T) {
for _, leaf := range leaves {
got[leaf.Path] = true
}
for _, want := range []string{"github.attention.admitter.<key>", "github.attention.flap_window"} {
for _, want := range []string{"github.attention.admitter.<key>", "github.attention.flap_window", "github.attention.recipient_budget", "github.attention.digest_recipients[]"} {
if !got[want] {
t.Errorf("leaf %q must be enumerated", want)
}
Expand Down
1 change: 1 addition & 0 deletions src/pkg/attention/ack.go
Original file line number Diff line number Diff line change
Expand Up @@ -166,6 +166,7 @@ func (s *Store) Apply(repo string, item int, actor string, maintainer bool, cmd
e.SnoozedBy = actor
}
e.WouldNotify = false
s.releaseBudget(e)
out = append(out, *e)
}
if err := s.save(); err != nil {
Expand Down
186 changes: 186 additions & 0 deletions src/pkg/attention/budget_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,186 @@
package attention

import (
"context"
"fmt"
"path/filepath"
"strings"
"testing"
"time"

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

func budgetConfig(n int, digest ...string) Config {
return Config{Admitter: testConfig.Admitter, Config: attentionbudget.Config{RecipientBudget: n, DigestRecipients: digest}}
}

// asks returns n distinct actionable observations for the same recipient.
func asks(n int, class attentionbudget.Class) []Observation {
var out []Observation
for i := 0; i < n; i++ {
o := observation()
o.Key.Subject = fmt.Sprintf("%s-%d", class, i)
o.Class = class
out = append(out, o)
}
return out
}

func reportWith(t *testing.T, s *Store, cfg Config, f *forge, obs ...Observation) []Episode {
t.Helper()
es, err := s.Report(context.Background(), cfg, "owner", "org/repo", 1, obs, f)
if err != nil {
t.Fatal(err)
}
return es
}

func TestBudgetDisabledChangesNothing(t *testing.T) {
s := openStore(t, "")
f := &forge{}
es := report(t, s, f, "owner", asks(attentionbudget.ShadowBudget+2, "")...)
if len(f.posts) != attentionbudget.ShadowBudget+2 {
t.Fatalf("disabled budget held back asks: posts=%d", len(f.posts))
}
for _, e := range es {
if e.Overflowed || e.State != Notified {
t.Fatalf("disabled budget changed an episode: %+v", e)
}
}
if c := s.Budget().Snapshot()["maintainer"]; c.Delivered != len(f.posts) || c.WouldOverflow != 2 || c.Overflowed != 0 {
t.Fatalf("shadow counts = %+v", c)
}
if line := s.Budget().LogLine(); !strings.HasPrefix(line, "attention budget: off") || !strings.Contains(line, "would_overflow=2") {
t.Fatalf("shadow log line = %q", line)
}
}

func TestBudgetOverflowIsRecordedNotDropped(t *testing.T) {
s := openStore(t, "")
f := &forge{}
cfg := budgetConfig(2, "maintainer")
obs := asks(3, "")
es := reportWith(t, s, cfg, f, obs...)
if len(f.posts) != 2 {
t.Fatalf("(N+1)th ask posted: posts=%d", len(f.posts))
}
held := obs[2].Key.Hash()
var found bool
for _, e := range es {
if e.Key.Hash() != held {
continue
}
found = true
if !e.Overflowed || e.State != Actionable || !e.WouldNotify || !e.PagedAt.IsZero() {
t.Fatalf("overflowed ask not kept open: %+v", e)
}
}
if !found {
t.Fatal("overflowed ask dropped from the ledger")
}
open := s.OpenEpisodes("org/repo")
if len(open) != 3 {
t.Fatalf("overflowed ask missing from the action queue: %d open", len(open))
}
over := s.Budget().Overflowed("org/repo", "maintainer", 1)
if len(over) != 1 || over[0].Key != held {
t.Fatalf("overflowed ask not visible: %+v", over)
}
if !strings.Contains(attentionbudget.RenderSection(over), "#1") || !strings.Contains(attentionbudget.RenderDigest("maintainer", over), "#1") {
t.Fatal("overflowed ask not rendered for the status card and digest")
}
// The next report retries, still held, and never double-posts.
reportWith(t, s, cfg, f, obs...)
if len(f.posts) != 2 {
t.Fatalf("held ask posted while over budget: posts=%d", len(f.posts))
}
// Resolving the episode clears the overflowed entry.
resolved := obs[2]
resolved.Resolved = true
reportWith(t, s, cfg, f, obs[0], obs[1], resolved)
if over := s.Budget().Overflowed("org/repo", "", 0); len(over) != 0 {
t.Fatalf("resolved ask still listed: %+v", over)
}
}

func TestBudgetNotOptedInKeepsNewAsks(t *testing.T) {
s := openStore(t, "")
f := &forge{}
reportWith(t, s, budgetConfig(1), f, asks(3, "")...)
if len(f.posts) != 3 {
t.Fatalf("recipient without digest lost a new ask: posts=%d", len(f.posts))
}
}

func TestBudgetExemptClassesAlwaysDeliver(t *testing.T) {
for _, class := range []attentionbudget.Class{attentionbudget.Security, attentionbudget.RequiredReview, attentionbudget.ProtocolCommand, attentionbudget.Hold} {
t.Run(string(class), func(t *testing.T) {
s := openStore(t, "")
f := &forge{}
cfg := budgetConfig(1, "maintainer")
obs := append(asks(1, ""), asks(3, class)...)
es := reportWith(t, s, cfg, f, obs...)
if len(f.posts) != 4 {
t.Fatalf("exempt %s ask held by budget: posts=%d", class, len(f.posts))
}
for _, e := range es {
if e.Overflowed {
t.Fatalf("exempt episode overflowed: %+v", e)
}
}
for _, e := range es {
if e.Class != class {
continue
}
if d, err := s.AdmitReminder(cfg, e, time.Now()); err != nil || d.Outcome != attentionbudget.Deliver {
t.Fatalf("exempt %s reminder held: %+v %v", class, d, err)
}
}
})
}
}

func TestBudgetReminderOverflowAndSeedFromLedger(t *testing.T) {
path := filepath.Join(t.TempDir(), "episodes.json")
s := openStore(t, path)
f := &forge{}
cfg := budgetConfig(1, "maintainer")
es := reportWith(t, s, cfg, f, asks(1, "")...)
if len(f.posts) != 1 || len(es) != 1 {
t.Fatalf("posts=%d", len(f.posts))
}
// A restart reseeds the window from paged_to/paged_at.
s = openStore(t, path)
d, err := s.AdmitReminder(cfg, es[0], time.Now())
if err != nil || d.Outcome != attentionbudget.Overflow || !d.Digest {
t.Fatalf("reminder over a seeded budget = %+v %v", d, err)
}
if got := s.Snapshot("org/repo", 1); len(got) != 1 || !got[0].Overflowed {
t.Fatalf("held reminder not recorded: %+v", got)
}
if over := s.Budget().Overflowed("org/repo", "maintainer", 0); len(over) != 1 || over[0].Class != attentionbudget.Reminder {
t.Fatalf("held reminder not visible: %+v", over)
}
if _, err := s.Apply("org/repo", 1, "maintainer", false, Command{Kind: CommandAck, Target: es[0].Key.Hash()[:12]}); err != nil {
t.Fatal(err)
}
if over := s.Budget().Overflowed("org/repo", "", 0); len(over) != 0 {
t.Fatalf("acknowledged reminder still listed: %+v", over)
}
// Disabled, the same reminder is delivered.
if d, err := s.AdmitReminder(testConfig, es[0], time.Now()); err != nil || d.Outcome != attentionbudget.Deliver {
t.Fatalf("disabled budget held a reminder: %+v %v", d, err)
}
}

func TestConfigValidatesBudget(t *testing.T) {
for _, cfg := range []Config{budgetConfig(-1), budgetConfig(attentionbudget.MaxRecipientBudget + 1), budgetConfig(1, "a", "A")} {
if err := cfg.Validate(); err == nil {
t.Fatalf("accepted invalid budget config: %+v", cfg.Config)
}
}
if err := budgetConfig(3, "alice").Validate(); err != nil {
t.Fatal(err)
}
}
Loading
Loading