From db345f59cefaae128b54aed4a2014b25cd87b331 Mon Sep 17 00:00:00 2001 From: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Mon, 2 Nov 2026 16:56:21 -0500 Subject: [PATCH 1/4] =?UTF-8?q?=E2=9C=A8=20feat(notifications):=20shadow-m?= =?UTF-8?q?ode=20would-notify=20instrumentation=20and=20write-site=20class?= =?UTF-8?q?ification?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- .../added-16264-notification-shadow-mode.md | 1 + src/cmd/hive/main_sweeps.go | 3 + src/docs/notifications.md | 186 +++++++ .../sweeps-and-operations.md | 8 + src/pkg/config/github_notifications.go | 6 + src/pkg/config/github_notifications_test.go | 6 + .../dashboard/metrics_github_notifications.go | 70 +++ .../metrics_github_notifications_test.go | 53 ++ src/pkg/dashboard/metrics_prometheus.go | 6 + src/pkg/github/client.go | 9 + src/pkg/github/issue_request_review.go | 1 + src/pkg/github/notification_shadow.go | 503 ++++++++++++++++++ src/pkg/github/notification_shadow_test.go | 180 +++++++ src/pkg/github/notification_tally.go | 22 +- src/pkg/github/notification_write_sites.go | 117 ++++ .../github/notification_write_sites_test.go | 187 +++++++ src/pkg/github/pr_status_comment.go | 2 +- src/pkg/github/review_request_watcher.go | 6 + 18 files changed, 1356 insertions(+), 10 deletions(-) create mode 100644 changelog.d/added-16264-notification-shadow-mode.md create mode 100644 src/pkg/dashboard/metrics_github_notifications.go create mode 100644 src/pkg/dashboard/metrics_github_notifications_test.go create mode 100644 src/pkg/github/notification_shadow.go create mode 100644 src/pkg/github/notification_shadow_test.go create mode 100644 src/pkg/github/notification_write_sites.go create mode 100644 src/pkg/github/notification_write_sites_test.go diff --git a/changelog.d/added-16264-notification-shadow-mode.md b/changelog.d/added-16264-notification-shadow-mode.md new file mode 100644 index 0000000000..5aba87e592 --- /dev/null +++ b/changelog.d/added-16264-notification-shadow-mode.md @@ -0,0 +1 @@ +- Added `github.notifications.shadow` (default off): would-notify instrumentation that classifies every notification-capable GitHub write by producer and class, counts repeats it would suppress, exports the counters on `/metrics`, and documents the write-site inventory — measurement only, no write changes (#16264). diff --git a/src/cmd/hive/main_sweeps.go b/src/cmd/hive/main_sweeps.go index ff773d7f47..d2ff9c1ac9 100644 --- a/src/cmd/hive/main_sweeps.go +++ b/src/cmd/hive/main_sweeps.go @@ -1983,6 +1983,9 @@ func installReviewRelaySettings(client *github.Client, cfg *config.Config, logge func() int { return cfg.Review.MaxReviewsPerHead }, ) client.SetNotificationsQuiet(func() bool { return cfg.GitHub.Notifications.Quiet() }) + // github.notifications.shadow (hivecommons/hive#16264): would-notify + // instrumentation only, read live; nothing is suppressed. + client.SetNotificationsShadow(func() bool { return cfg.GitHub.Notifications.Shadow }) // review.require_labels (PR approval allow-list): the relay's half of the // gate, read live so a Features-tab edit applies to the next request. client.SetReviewRequireLabels(func() []string { return cfg.Review.RequireLabels }) diff --git a/src/docs/notifications.md b/src/docs/notifications.md index 75ae147cdb..eb3f9da9ee 100644 --- a/src/docs/notifications.md +++ b/src/docs/notifications.md @@ -253,3 +253,189 @@ notifications: ``` The bot needs the `Create Public Threads` and `Send Messages in Threads` permissions, plus `Read Message History` for reconciliation. + +## GitHub writes: inventory and shadow mode (`github.notifications.shadow`) + +Every new issue/PR comment, review submission, review request and @-mention +the hive makes on GitHub emails the people involved and everyone watching the +repository. [`github.notifications.mode`](operator-reference/sweeps-and-operations.md#notification-mode-githubnotificationsmode) +already folds the hive's own bookkeeping into one edited status comment; +shadow mode measures what is left so a later change can be judged against a +baseline ([#16075](https://github.com/hivecommons/hive/issues/16075)). + +```yaml +github: + notifications: + shadow: true # default false +``` + +Shadow mode is **instrumentation only**: nothing is suppressed, delayed or +rerouted, and the GitHub writes are byte-for-byte the same with the flag on +or off. With the flag on, each notification-capable write the Go client makes +is attributed to its producer (the inventoried function below), classified, +and given a *would-notify* decision: + +- **Record** — `{repo, item, producer, class, condition key, would_notify, + reason}` plus the logins the write mentions or requests. Comment bodies, + other recipients and inbox contents are never kept. The last 512 records + stay in memory (`Client.NotificationShadowRecords`). +- **Condition key** (provisional) — `(repo, item, class, subject)`, where the + subject is what the writer supplies (the status-comment section key for + `PostNoteOrFold`) or the producer name. A later change defines the + authoritative, producer-independent key. +- **Decision** — a write whose condition key was already written within 24 + hours is `would_notify=false`, reason `repeat_condition`, **only** for the + `status` and `attention` classes. `protocol_command`, `required_review` and + `security_event` writes are always `would_notify=true` (a repeat gets reason + `exempt_class_repeat`). A failed write is `delivery_failed`. + +### Counters + +The hourly `github notifications` log line gains `shadow_would_suppress`, +`shadow_reviews`, `shadow_review_requests`, `shadow_mentions`, +`shadow_delivery_failures` and `shadow_active_items` while shadow mode is on +(the line is unchanged while it is off). The opt-in Prometheus endpoint +(`HIVE_METRICS_ENABLED` + `HIVE_METRICS_TOKEN`) exports: + +| Series | Labels | Meaning | +|---|---|---| +| `hive_github_comments_total` | `op` = `created` / `edited` / `suppressed` | The always-on comment tally. | +| `hive_github_notification_comments_created_total` | `producer`, `class` | New comments. | +| `hive_github_notification_reviews_submitted_total` | `producer`, `class` | Review submissions. | +| `hive_github_notification_review_requests_total` | `producer`, `class` | Review requests. | +| `hive_github_notification_mentions_total` | `producer`, `class` | @-mentions in posted comments and reviews. | +| `hive_github_notification_suppressed_repeats_total` | `producer`, `class` | Notes the hive actually did not post (folded or already present). | +| `hive_github_notification_would_suppress_repeats_total` | `producer`, `class` | Writes shadow mode *would* suppress. | +| `hive_github_notification_delivery_failures_total` | `producer`, `class` | Failed writes. | +| `hive_github_notification_active_items` | — | Items with a notification-capable write in the last 24 hours. | + +All counts are API writes, a proxy for notifications — never "emails +delivered". Counters are cumulative since process start. + +### Comparing baseline windows + +Compare **per active item**, over **matched windows**: the same length (a +whole week, so weekday traffic is matched), similar open-item load, and no +change to `github.notifications.mode` or the hive version inside either +window. For each window compute + +``` +writes = increase(hive_github_notification_comments_created_total[7d]) + + increase(hive_github_notification_reviews_submitted_total[7d]) + + increase(hive_github_notification_review_requests_total[7d]) +per_item = writes / avg_over_time(hive_github_notification_active_items[7d]) +repeat_rate = increase(hive_github_notification_would_suppress_repeats_total[7d]) + / avg_over_time(hive_github_notification_active_items[7d]) +``` + +broken down by `class` and `producer`. The baseline is a shadow-on window +before any suppression ships; the candidate is the same metrics after it. The +80% reduction in repeat/non-actionable writes per active item named in #16075 +is an **acceptance target**, not a measured or claimed result: shadow mode +only produces the baseline that target will be checked against. + +### Write-site inventory + +Every function under `src/pkg` and `src/cmd` that calls a notification-capable +write primitive (`CreateIssueComment`, `CreateIssueCommentBudgeted`, +`PostNoteOrFold`, `PostClaimNote`, `PullRequests.CreateReview`, +`RequestReviewers`) or records a suppressed note is listed here and in +`notificationWriteSites` (`src/pkg/github/notification_write_sites.go`). +`TestNotificationWriteSitesInventory` fails when a new call site is added +without a class. Review submissions and review requests are always counted as +`required_review`, whichever producer made them. + +- `status` — bookkeeping readable on demand; repeats may be would-suppress. +- `attention` — asks a person to look or act; repeats may be would-suppress. +- `required_review` — a review or review request a merge depends on; never would-suppress. +- `protocol_command` — machine-consumed (claim markers, `/lgtm`, `/approve`, `/ok-to-test`); never would-suppress. +- `security_event` — trust or integrity signal; never would-suppress. + +| Producer | Class | Notes | +|---|---|---| +| `dashboard.(*ContributeWSHub).markAlreadyDoneIssue` | `status` | | +| `dashboard.(*ContributeWSHub).releaseGateParkLabel` | `status` | | +| `dashboard.(*ContributeWSHub).releaseToolingBlockedLabel` | `status` | | +| `dashboard.(*Server).armRebaseThenMerge` | `status` | | +| `dashboard.(*Server).executeDelegatedDecision` | `status` | | +| `dashboard.(*Server).handlePullRequestMergeDecision` | `status` | | +| `dashboard.(*Server).handleRepoItemAdoptNow` | `status` | | +| `dashboard.(*Server).handleRepoItemBlockerClosePartial` | `status` | | +| `dashboard.(*Server).handleRepoItemDecision` | `status` | | +| `dashboard.(*Server).handleReviewQueueSupersededClose` | `status` | | +| `dashboard.(*Server).mirrorPlanWith` | `status` | | +| `github.(*Client).CloseIssueForConfiguredLinePR` | `status` | | +| `github.(*Client).CreateIssueCommentBudgeted` | `status` | passthrough wrapper; attributed to its caller | +| `github.(*Client).PostFleetReportCleared` | `status` | | +| `github.(*Client).PostFleetReportRecovery` | `status` | | +| `github.(*Client).PostFleetReportRollup` | `status` | | +| `github.(*Client).PostNoteOrFold` | `status` | passthrough wrapper; attributed to its caller | +| `github.(*Client).SweepLegacyFleetReportIssues` | `status` | | +| `github.(*Client).UpsertIssueMarkerComment` | `status` | passthrough wrapper; attributed to its caller | +| `github.(*Client).closeDecomposedParent` | `status` | | +| `github.(*Client).closeIssueForMergedPRClaimWithIssue` | `status` | | +| `github.(*Client).closeSupersededPRDecision` | `status` | | +| `github.(*Client).fileReviewBacklog` | `status` | | +| `github.(*Client).joinFleetReportIssue` | `status` | | +| `github.(*Client).markInProgressStarted` | `status` | | +| `github.(*Client).postUnblockedNote` | `status` | | +| `github.(*Client).priorArtGateClose` | `status` | | +| `github.(*Client).reconcileBlockedTargets` | `status` | | +| `github.(*Client).recordReviewEvidenceMerge` | `status` | | +| `github.SyncIssueStageLabelsWith` | `status` | | +| `github.ensureIssueStagePRLink` | `status` | | +| `github.githubIssueBacklogSink.AppendToItem` | `status` | | +| `github.githubIssueBacklogSink.CloseItem` | `status` | | +| `github.githubIssueBacklogSink.LiftBlock` | `status` | | +| `github.handleMergedPRIssueStage` | `status` | | +| `github.runRecheckSoak` | `status` | | +| `main.postReviewAcknowledgements` | `status` | | +| `main.rfcNotifySource.Comment` | `status` | | +| `main.unparkEscalatedPR` | `status` | | +| `dashboard.(*ContributeWSHub).parkWrongBase` | `attention` | | +| `dashboard.(*Server).handleRepoItemReroute` | `attention` | | +| `dashboard.(*Server).handleReviewPipelineSendToHuman` | `attention` | | +| `dashboard.(*Server).reroutePickupLapsed` | `attention` | | +| `dashboard.(*Server).settleRebaseMergeLedger` | `attention` | | +| `github.(*Client).NudgeTrackingIssueClosingRefs` | `attention` | | +| `github.(*Client).appendFoldedFinding` | `attention` | | +| `github.(*Client).bindProwLgtm` | `attention` | | +| `github.(*Client).commentOnHumanFiledTwin` | `attention` | | +| `github.(*Client).createIssue` | `attention` | | +| `github.(*Client).handleOneIssueRequest` | `attention` | | +| `github.(*Client).parkClankerRequestedPR` | `attention` | | +| `github.(*Client).redirectToExistingPR` | `attention` | | +| `github.(*Client).resolveDuplicateFixGroup` | `attention` | | +| `main.(*repoForgeRouter).CreateIssueComment` | `attention` | passthrough wrapper; attributed to its caller | +| `main.claimEscalationLookup` | `attention` | | +| `main.liveTriageCommenter.CreateIssueComment` | `attention` | passthrough wrapper; attributed to its caller | +| `main.maintainHeldPRMergeability` | `attention` | | +| `main.rfcCoverageForge.CreateComment` | `attention` | | +| `main.runEscalationSweep` | `attention` | | +| `prfollowup.postStaleHeadPushNotes` | `attention` | | +| `scheduler.(*Scheduler).judgePriorArt` | `attention` | | +| `scheduler.(*Scheduler).parkUnclearIssue` | `attention` | | +| `scheduler.(*Scheduler).postTriageClarifyComment` | `attention` | | +| `github.(*Client).QueuePRAutoMergeWithNoteResult` | `required_review` | | +| `github.(*Client).RequestReviewers` | `required_review` | passthrough wrapper; attributed to its caller | +| `github.(*Client).handleOneReviewRequest` | `required_review` | | +| `dashboard.postClaimComment` | `protocol_command` | | +| `github.(*Client).PostClaimNote` | `protocol_command` | | +| `github.(*Client).RecordOperatorPullRequestApprovalWith` | `protocol_command` | | +| `main.githubClaimHooks` | `protocol_command` | | +| `github.(*Client).handleOnePRRequest` | `security_event` | | +| `github.(*Client).markReporterTrustAwaiting` | `security_event` | | +| `github.(*Client).reconcileReporterTrustSignal` | `security_event` | | +| `main.enforceHoldGuard` | `security_event` | | + +Hive-maintained GitHub Actions workflows that comment (not instrumented by the +Go client; listed for completeness): + +| Workflow | Class | What it posts | +|---|---|---| +| `changelog-fragment-guard.yml`, `changelog-reminder.yml`, `docs-index-reminder.yml` | `status` | PR reminders about changelog fragments and the docs index. | +| `issue-closed-reopen-hint.yml`, `issue-reopen-command.yml` | `status` | Reopen hint on closed issues; reply to a reopen command. | +| `backend-smoke.yml`, `ci-runner-canary.yml`, `coverage-hourly.yml`, `dco-post-merge.yml`, `flue-smoke.yml`, `omp-smoke.yml`, `wavefront-smoke.yml`, `v2-ci.yml`, `v2-tests.yml` | `attention` | "Still failing" comments on an open failure-tracking issue. | +| `promote-stable.yml` | `attention` | Emergency stable-promotion exception note. | +| `weekly-competitor-report.md` (`.lock.yml`) | `status` | Weekly report comment on the tracking issue. | +| `hive-ok-to-test.yml` | `protocol_command` | The `/ok-to-test` command that releases held workflow runs. | diff --git a/src/docs/operator-reference/sweeps-and-operations.md b/src/docs/operator-reference/sweeps-and-operations.md index 0cdebfbd0c..aa47ccbebc 100644 --- a/src/docs/operator-reference/sweeps-and-operations.md +++ b/src/docs/operator-reference/sweeps-and-operations.md @@ -586,6 +586,14 @@ already present), so the effect of the mode can be charted from the logs. `normal` restores the previous behaviour: every note is its own comment, every perspective's verdict its own review, every new head its own mention. +`github.notifications.shadow: true` (default off) adds would-notify +instrumentation without changing any write: every new comment, review, +review request and @-mention is classified by producer and class, repeats of +the same condition are counted as would-suppress, and the counters are +exported on `/metrics`. See [GitHub writes: inventory and shadow +mode](../notifications.md#github-writes-inventory-and-shadow-mode-githubnotificationsshadow) +for the write-site inventory and how to compare baseline windows. + ## Suspicious-activity alerts (`sentinel`) The sentinel evaluates open PRs in the watched repos — human, bot, or agent — diff --git a/src/pkg/config/github_notifications.go b/src/pkg/config/github_notifications.go index 807e1d8b83..0a9e7541c2 100644 --- a/src/pkg/config/github_notifications.go +++ b/src/pkg/config/github_notifications.go @@ -25,6 +25,12 @@ const ( type GitHubNotificationsConfig struct { // Mode is "quiet" (default when empty) or "normal". Mode string `yaml:"mode,omitempty" json:"mode,omitempty"` + // Shadow turns on would-notify instrumentation: every + // notification-capable GitHub write (new comment, review, review + // request, @-mention) is classified and counted, and a would-suppress + // decision is recorded for repeats of the same condition. Measurement + // only — nothing is suppressed or rerouted. Default off. + Shadow bool `yaml:"shadow,omitempty" json:"shadow,omitempty"` } // Quiet reports whether the hive should fold its PR notes into one edited diff --git a/src/pkg/config/github_notifications_test.go b/src/pkg/config/github_notifications_test.go index 9cbf14454a..1cf95eab7a 100644 --- a/src/pkg/config/github_notifications_test.go +++ b/src/pkg/config/github_notifications_test.go @@ -16,3 +16,9 @@ func TestGitHubNotificationsConfig(t *testing.T) { t.Error("unknown mode must be invalid") } } + +func TestGitHubNotificationsShadowDefaultsOff(t *testing.T) { + if (GitHubNotificationsConfig{}).Shadow { + t.Fatal("github.notifications.shadow must default to off") + } +} diff --git a/src/pkg/dashboard/metrics_github_notifications.go b/src/pkg/dashboard/metrics_github_notifications.go new file mode 100644 index 0000000000..b197445a43 --- /dev/null +++ b/src/pkg/dashboard/metrics_github_notifications.go @@ -0,0 +1,70 @@ +package dashboard + +import ( + "fmt" + "strings" + + ghpkg "github.com/hivecommons/hive/pkg/github" +) + +// githubNotificationSnapshot is what /metrics exports about the hive's +// notification-capable GitHub writes: the always-on comment tally and, when +// github.notifications.shadow is on, the shadow counters. +type githubNotificationSnapshot struct { + Created, Edited, Suppressed int64 + Shadow bool + Counts []ghpkg.NotificationShadowCount + ActiveItems int +} + +func githubNotificationSnapshotFrom(c *ghpkg.Client) githubNotificationSnapshot { + var snap githubNotificationSnapshot + if c == nil { + return snap + } + snap.Created, snap.Edited, snap.Suppressed = c.NotificationCounts() + snap.Counts = c.NotificationShadowCounts() + snap.Shadow = c.NotificationShadowEnabled() || len(snap.Counts) > 0 + snap.ActiveItems = c.NotificationShadowActiveItems() + return snap +} + +var githubNotificationShadowMetricHelp = []struct{ metric, help string }{ + {ghpkg.NotificationMetricCommentsCreated, "New issue/PR comments the hive created (API writes, not emails delivered), by producer and class."}, + {ghpkg.NotificationMetricReviewsSubmitted, "PR reviews the hive submitted, by producer and class."}, + {ghpkg.NotificationMetricReviewRequests, "Review requests the hive made, by producer and class."}, + {ghpkg.NotificationMetricMentions, "@-mentions carried by comments and reviews the hive posted, by producer and class."}, + {ghpkg.NotificationMetricSuppressedRepeats, "Notes the hive chose not to post as a new comment (folded or already present), by producer and class."}, + {ghpkg.NotificationMetricWouldSuppressRepeats, "Writes shadow mode would have suppressed as a repeat of the same condition, by producer and class. Nothing is suppressed."}, + {ghpkg.NotificationMetricDeliveryFailures, "Notification-capable writes that failed, by producer and class."}, +} + +// writeGitHubNotificationMetrics emits hive_github_comments_total and, when +// shadow mode is or was on, the hive_github_notification_* series. +func writeGitHubNotificationMetrics(b *strings.Builder, hiveID string, writeHeader func(name, help, typ string), snap githubNotificationSnapshot) { + writeHeader("hive_github_comments_total", + "Hive comments since process start by operation: created (notifies), edited (does not), suppressed (folded or already present).", "counter") + for _, op := range []struct { + name string + v int64 + }{{"created", snap.Created}, {"edited", snap.Edited}, {"suppressed", snap.Suppressed}} { + fmt.Fprintf(b, "hive_github_comments_total{hive_id=%s,op=%s} %d\n", promQuote(hiveID), promQuote(op.name), op.v) + } + if !snap.Shadow { + return + } + for _, m := range githubNotificationShadowMetricHelp { + name := "hive_github_notification_" + m.metric + "_total" + writeHeader(name, m.help, "counter") + for _, c := range snap.Counts { + if c.Metric != m.metric { + continue + } + fmt.Fprintf(b, "%s{hive_id=%s,producer=%s,class=%s} %d\n", + name, promQuote(hiveID), promQuote(c.Producer), promQuote(string(c.Class)), c.Value) + } + } + writeHeader("hive_github_notification_active_items", + "Issues and PRs that received a notification-capable hive write in the last 24 hours; the per-active-item denominator.", "gauge") + fmt.Fprintf(b, "hive_github_notification_active_items{hive_id=%s} %d\n", promQuote(hiveID), snap.ActiveItems) +} diff --git a/src/pkg/dashboard/metrics_github_notifications_test.go b/src/pkg/dashboard/metrics_github_notifications_test.go new file mode 100644 index 0000000000..1911364e64 --- /dev/null +++ b/src/pkg/dashboard/metrics_github_notifications_test.go @@ -0,0 +1,53 @@ +package dashboard + +import ( + "fmt" + "strings" + "testing" + + ghpkg "github.com/hivecommons/hive/pkg/github" +) + +func TestWriteGitHubNotificationMetrics(t *testing.T) { + render := func(snap githubNotificationSnapshot) string { + var b strings.Builder + writeHeader := func(name, help, typ string) { + fmt.Fprintf(&b, "# HELP %s %s\n# TYPE %s %s\n", name, help, name, typ) + } + writeGitHubNotificationMetrics(&b, "h1", writeHeader, snap) + return b.String() + } + + off := render(githubNotificationSnapshot{Created: 3, Edited: 2, Suppressed: 1}) + for _, want := range []string{ + `hive_github_comments_total{hive_id="h1",op="created"} 3`, + `hive_github_comments_total{hive_id="h1",op="edited"} 2`, + `hive_github_comments_total{hive_id="h1",op="suppressed"} 1`, + } { + if !strings.Contains(off, want) { + t.Errorf("missing %q in:\n%s", want, off) + } + } + if strings.Contains(off, "hive_github_notification_") { + t.Errorf("shadow series emitted while shadow is off:\n%s", off) + } + + on := render(githubNotificationSnapshot{ + Shadow: true, + Counts: []ghpkg.NotificationShadowCount{ + {Metric: ghpkg.NotificationMetricWouldSuppressRepeats, Producer: "github.(*Client).postUnblockedNote", Class: ghpkg.NotificationClassStatus, Value: 4}, + {Metric: ghpkg.NotificationMetricReviewRequests, Producer: "github.(*Client).RequestReviewers", Class: ghpkg.NotificationClassRequiredReview, Value: 1}, + }, + ActiveItems: 7, + }) + for _, want := range []string{ + `hive_github_notification_would_suppress_repeats_total{hive_id="h1",producer="github.(*Client).postUnblockedNote",class="status"} 4`, + `hive_github_notification_review_requests_total{hive_id="h1",producer="github.(*Client).RequestReviewers",class="required_review"} 1`, + `# TYPE hive_github_notification_delivery_failures_total counter`, + `hive_github_notification_active_items{hive_id="h1"} 7`, + } { + if !strings.Contains(on, want) { + t.Errorf("missing %q in:\n%s", want, on) + } + } +} diff --git a/src/pkg/dashboard/metrics_prometheus.go b/src/pkg/dashboard/metrics_prometheus.go index f095f30b6f..088a2dab36 100644 --- a/src/pkg/dashboard/metrics_prometheus.go +++ b/src/pkg/dashboard/metrics_prometheus.go @@ -71,6 +71,9 @@ func metricsToken() string { // hive_stage_transition_anomaly_total{hive_id,kind,from,to} — transitions the admission table rejected // hive_stage_writer_writes_total{hive_id,kind,op} — label writes by the single StageWriter // hive_stage_duplicate_pills_healed_total{hive_id,kind} — duplicate stage pills the writer removed +// hive_github_comments_total{hive_id,op} — hive comments created / edited / suppressed +// hive_github_notification__total{hive_id,producer,class} — github.notifications.shadow counters +// hive_github_notification_active_items{hive_id} — items with a notification-capable write in 24h (shadow) // // The hive_pr_followup_* series (#9583) appear only once the PR follow-up // resume feature has written its counter file. @@ -179,6 +182,9 @@ func (s *Server) handleMetrics(w http.ResponseWriter, r *http.Request) { writePRFollowUpMetrics(&b, hiveID, writeHeader) writeTrajectoryMetrics(&b, hiveID, writeHeader) writeStageEngineMetrics(&b, hiveID, writeHeader, stageengine.DefaultCounters()) + if s.deps != nil && s.deps.GHClient != nil { + writeGitHubNotificationMetrics(&b, hiveID, writeHeader, githubNotificationSnapshotFrom(s.deps.GHClient)) + } w.Header().Set("Content-Type", "text/plain; version=0.0.4; charset=utf-8") _, _ = w.Write([]byte(b.String())) diff --git a/src/pkg/github/client.go b/src/pkg/github/client.go index 7e3236bc35..c59e1a711e 100644 --- a/src/pkg/github/client.go +++ b/src/pkg/github/client.go @@ -278,6 +278,11 @@ type Client struct { // notifications counts comments created, edited and suppressed; logged // hourly so the effect of quiet mode is measurable. notifications notificationTally + // shadowNotificationsFn is github.notifications.shadow, read live: when + // it returns true every notification-capable write is classified and + // recorded in notificationShadow. nil reads as off. + shadowNotificationsFn func() bool + notificationShadow notificationShadow // reviewRequireLabelsFn returns review.require_labels, read live so a // Features-tab edit gates the next relay request without a rebuild. nil // or empty means the gate is off. @@ -2963,6 +2968,7 @@ func (c *Client) CreateIssueComment(ctx context.Context, repo string, number int if err == nil { c.noteCommentCreated() } + c.recordNotificationWrite(ctx, notificationWrite{kind: notificationWriteComment, repo: owner + "/" + repoName, item: number, body: body, err: err}) return err } @@ -3188,6 +3194,9 @@ func (c *Client) QueuePRAutoMergeWithNoteResult(ctx context.Context, repo string } return effects.Result{Provenance: provenance}, apiErr }) + if !refusedAsOwn { + c.recordNotificationWrite(ctx, notificationWrite{kind: notificationWriteReview, repo: full, item: number, body: body, class: NotificationClassRequiredReview, err: err}) + } if err != nil { return res, fmt.Errorf("approving PR: %w", err) } diff --git a/src/pkg/github/issue_request_review.go b/src/pkg/github/issue_request_review.go index e8d28b4a5a..6d624f6338 100644 --- a/src/pkg/github/issue_request_review.go +++ b/src/pkg/github/issue_request_review.go @@ -124,5 +124,6 @@ func (c *Client) RequestReviewers(ctx context.Context, repo string, number int, }) return effects.Result{Provenance: owner + "/" + repoName + "#" + strconv.Itoa(number)}, apiErr }) + c.recordNotificationWrite(ctx, notificationWrite{kind: notificationWriteReviewRequest, repo: owner + "/" + repoName, item: number, requested: reviewers, class: NotificationClassRequiredReview, err: err}) return err } diff --git a/src/pkg/github/notification_shadow.go b/src/pkg/github/notification_shadow.go new file mode 100644 index 0000000000..856ba13fb1 --- /dev/null +++ b/src/pkg/github/notification_shadow.go @@ -0,0 +1,503 @@ +package github + +import ( + "context" + "regexp" + "runtime" + "sort" + "strconv" + "strings" + "sync" + "time" +) + +// Shadow-mode would-notify instrumentation (github.notifications.shadow, +// hivecommons/hive#16264). Every notification-capable write the client +// makes — a new issue/PR comment, a review submission, a review request, +// and the @-mentions a comment or review body carries — is attributed to +// its producer (the inventoried function that asked for it, see +// notificationWriteSites), classified, and given a would-notify decision. +// Nothing is suppressed or rerouted: the decision is recorded, never acted +// on, and with the flag off the recording path returns before doing any +// work. Comment bodies, inbox contents and recipient lists are never kept; +// a record carries only the logins a write mentions or requests. + +// NotificationClass is why a notification-capable write happened. +type NotificationClass string + +const ( + // NotificationClassStatus is bookkeeping a person can read on demand: + // stage notes, fleet reports, close/unblock notes, operator decision + // records. Repeats of the same condition are would-suppress candidates. + NotificationClassStatus NotificationClass = "status" + // NotificationClassAttention asks a person to look or act (parked, + // escalated, duplicate, clarification needed). Repeats of the same + // condition are would-suppress candidates. + NotificationClassAttention NotificationClass = "attention" + // NotificationClassRequiredReview is a review submission or review + // request a merge depends on. Never would-suppress. + NotificationClassRequiredReview NotificationClass = "required_review" + // NotificationClassProtocolCommand is a machine-consumed comment + // (claim/release markers, /lgtm, /approve, /ok-to-test). Never + // would-suppress: a reader acts on every instance. + NotificationClassProtocolCommand NotificationClass = "protocol_command" + // NotificationClassSecurityEvent is a trust or integrity signal + // (reporter trust, self-authorization, hold-guard drift). Never + // would-suppress. + NotificationClassSecurityEvent NotificationClass = "security_event" + // NotificationClassUnclassified marks a write whose producer is not in + // the inventory. The inventory guard test keeps this at zero for call + // sites under src/pkg and src/cmd. + NotificationClassUnclassified NotificationClass = "unclassified" +) + +// Suppressible reports whether a repeat of the same condition in this class +// may be marked would-suppress. Protocol commands, required reviews and +// security events are always delivered. +func (c NotificationClass) Suppressible() bool { + return c == NotificationClassStatus || c == NotificationClassAttention +} + +// Shadow counter names, exported as the metric label/series suffixes. +const ( + NotificationMetricCommentsCreated = "comments_created" + NotificationMetricReviewsSubmitted = "reviews_submitted" + NotificationMetricReviewRequests = "review_requests" + NotificationMetricMentions = "mentions" + NotificationMetricSuppressedRepeats = "suppressed_repeats" + NotificationMetricWouldSuppressRepeats = "would_suppress_repeats" + NotificationMetricDeliveryFailures = "delivery_failures" +) + +// Would-notify reasons carried by a NotificationShadowRecord. +const ( + NotificationReasonNewCondition = "new_condition" + NotificationReasonRepeatCondition = "repeat_condition" + NotificationReasonExemptRepeat = "exempt_class_repeat" + NotificationReasonDeliveryFailed = "delivery_failed" +) + +const ( + // notificationShadowWindow is how long a condition key counts as + // already notified, and how long an item counts as active. + notificationShadowWindow = 24 * time.Hour + // notificationShadowMaxKeys bounds the condition and active-item maps. + notificationShadowMaxKeys = 20000 + // notificationShadowLogSize bounds the local would-notify log. + notificationShadowLogSize = 512 + // notificationShadowMaxLogins bounds the logins kept per record. + notificationShadowMaxLogins = 10 +) + +type notificationWriteKind string + +const ( + notificationWriteComment notificationWriteKind = "comment" + notificationWriteReview notificationWriteKind = "review" + notificationWriteReviewRequest notificationWriteKind = "review_request" +) + +// NotificationShadowRecord is one would-notify decision. It never carries a +// comment body; Logins holds only the logins the write mentions or requests. +type NotificationShadowRecord struct { + At time.Time `json:"at"` + Repo string `json:"repo"` + Item int `json:"item"` + Kind string `json:"kind"` + Producer string `json:"producer"` + Class NotificationClass `json:"class"` + // ConditionKey is the provisional shadow key (repo, item, class, + // writer-supplied subject); the producer name stands in when the + // writer supplied no subject. + ConditionKey string `json:"condition_key"` + WouldNotify bool `json:"would_notify"` + Reason string `json:"reason"` + Logins []string `json:"logins,omitempty"` +} + +// NotificationShadowCount is one shadow counter value. +type NotificationShadowCount struct { + Metric string + Producer string + Class NotificationClass + Value int64 +} + +type notificationShadowCounterKey struct { + metric string + producer string + class NotificationClass +} + +// notificationShadow holds the shadow counters, the condition and +// active-item memories, and the bounded would-notify log. +type notificationShadow struct { + mu sync.Mutex + counters map[notificationShadowCounterKey]int64 + conditions map[string]time.Time + items map[string]time.Time + log []NotificationShadowRecord + next int +} + +type notificationSubjectKey struct{} + +// WithNotificationSubject attaches the writer-supplied subject of the +// provisional condition key to ctx. A write without one uses its producer +// name as the subject. +func WithNotificationSubject(ctx context.Context, subject string) context.Context { + if ctx == nil || strings.TrimSpace(subject) == "" { + return ctx + } + return context.WithValue(ctx, notificationSubjectKey{}, subject) +} + +func notificationSubjectFrom(ctx context.Context) string { + if ctx == nil { + return "" + } + s, _ := ctx.Value(notificationSubjectKey{}).(string) + return s +} + +// SetNotificationsShadow wires github.notifications.shadow. Read live so a +// config reload applies to the next write. nil (nothing wired) is off. +func (c *Client) SetNotificationsShadow(fn func() bool) { + if c == nil { + return + } + c.shadowNotificationsFn = fn +} + +func (c *Client) notificationsShadow() bool { + return c != nil && c.shadowNotificationsFn != nil && c.shadowNotificationsFn() +} + +// notificationWrite describes one notification-capable write at the +// boundary. body is scanned for @-mentions and then dropped. +type notificationWrite struct { + kind notificationWriteKind + repo string + item int + body string + requested []string + class NotificationClass + err error +} + +// recordNotificationWrite records the would-notify decision for one write. +// A no-op unless github.notifications.shadow is on. +func (c *Client) recordNotificationWrite(ctx context.Context, w notificationWrite) { + if !c.notificationsShadow() { + return + } + producer, site := attributeNotificationWrite() + class := site.Class + if w.class != "" { + class = w.class + } + subject := notificationSubjectFrom(ctx) + if subject == "" { + subject = producer + } + logins := w.requested + mentions := 0 + if w.kind != notificationWriteReviewRequest { + logins = extractMentionLogins(w.body) + mentions = len(logins) + } + if len(logins) > notificationShadowMaxLogins { + logins = logins[:notificationShadowMaxLogins] + } + rec := NotificationShadowRecord{ + At: notificationTallyNow(), + Repo: w.repo, + Item: w.item, + Kind: string(w.kind), + Producer: producer, + Class: class, + ConditionKey: w.repo + "#" + strconv.Itoa(w.item) + "|" + string(class) + "|" + subject, + Logins: append([]string(nil), logins...), + } + c.notificationShadow.record(&rec, w, mentions) + c.notifications.maybeLog(c.logger, c.notificationShadowLogAttrs()...) +} + +func (s *notificationShadow) record(rec *NotificationShadowRecord, w notificationWrite, mentions int) { + s.mu.Lock() + defer s.mu.Unlock() + if s.counters == nil { + s.counters = map[notificationShadowCounterKey]int64{} + s.conditions = map[string]time.Time{} + s.items = map[string]time.Time{} + } + now := rec.At + bump := func(metric string, n int64) { + if n > 0 { + s.counters[notificationShadowCounterKey{metric, rec.Producer, rec.Class}] += n + } + } + if w.err != nil { + rec.Reason = NotificationReasonDeliveryFailed + bump(NotificationMetricDeliveryFailures, 1) + s.appendLog(*rec) + return + } + switch w.kind { + case notificationWriteComment: + bump(NotificationMetricCommentsCreated, 1) + case notificationWriteReview: + bump(NotificationMetricReviewsSubmitted, 1) + case notificationWriteReviewRequest: + bump(NotificationMetricReviewRequests, 1) + } + bump(NotificationMetricMentions, int64(mentions)) + + last, seen := s.conditions[rec.ConditionKey] + repeat := seen && now.Sub(last) < notificationShadowWindow + switch { + case repeat && rec.Class.Suppressible(): + rec.WouldNotify = false + rec.Reason = NotificationReasonRepeatCondition + bump(NotificationMetricWouldSuppressRepeats, 1) + case repeat: + rec.WouldNotify = true + rec.Reason = NotificationReasonExemptRepeat + default: + rec.WouldNotify = true + rec.Reason = NotificationReasonNewCondition + } + s.conditions[rec.ConditionKey] = now + s.items[rec.Repo+"#"+strconv.Itoa(rec.Item)] = now + pruneNotificationShadowMap(s.conditions, now) + pruneNotificationShadowMap(s.items, now) + s.appendLog(*rec) +} + +func (s *notificationShadow) appendLog(rec NotificationShadowRecord) { + if len(s.log) < notificationShadowLogSize { + s.log = append(s.log, rec) + return + } + s.log[s.next] = rec + s.next = (s.next + 1) % notificationShadowLogSize +} + +// pruneNotificationShadowMap keeps m bounded: entries older than the window +// go first, then arbitrary ones until it fits. +func pruneNotificationShadowMap(m map[string]time.Time, now time.Time) { + if len(m) <= notificationShadowMaxKeys { + return + } + for k, t := range m { + if now.Sub(t) >= notificationShadowWindow { + delete(m, k) + } + } + for k := range m { + if len(m) <= notificationShadowMaxKeys { + break + } + delete(m, k) + } +} + +// noteShadowSuppressed counts a note the hive actually chose not to post, +// labelled by its producer. A no-op unless shadow mode is on. +func (c *Client) noteShadowSuppressed() { + if !c.notificationsShadow() { + return + } + producer, site := attributeNotificationWrite() + c.notificationShadow.mu.Lock() + if c.notificationShadow.counters == nil { + c.notificationShadow.counters = map[notificationShadowCounterKey]int64{} + c.notificationShadow.conditions = map[string]time.Time{} + c.notificationShadow.items = map[string]time.Time{} + } + c.notificationShadow.counters[notificationShadowCounterKey{NotificationMetricSuppressedRepeats, producer, site.Class}]++ + c.notificationShadow.mu.Unlock() +} + +// NotificationShadowCounts returns the shadow counters, sorted by metric, +// producer and class. Empty while shadow mode has never been on. +func (c *Client) NotificationShadowCounts() []NotificationShadowCount { + if c == nil { + return nil + } + s := &c.notificationShadow + s.mu.Lock() + out := make([]NotificationShadowCount, 0, len(s.counters)) + for k, v := range s.counters { + out = append(out, NotificationShadowCount{Metric: k.metric, Producer: k.producer, Class: k.class, Value: v}) + } + s.mu.Unlock() + sort.Slice(out, func(i, j int) bool { + a, b := out[i], out[j] + if a.Metric != b.Metric { + return a.Metric < b.Metric + } + if a.Producer != b.Producer { + return a.Producer < b.Producer + } + return a.Class < b.Class + }) + return out +} + +// NotificationShadowActiveItems is the number of distinct issues/PRs that +// received a notification-capable write in the last 24 hours — the +// denominator for per-active-item rates. +func (c *Client) NotificationShadowActiveItems() int { + if c == nil { + return 0 + } + s := &c.notificationShadow + now := notificationTallyNow() + s.mu.Lock() + defer s.mu.Unlock() + n := 0 + for _, t := range s.items { + if now.Sub(t) < notificationShadowWindow { + n++ + } + } + return n +} + +// NotificationShadowEnabled reports whether github.notifications.shadow is on. +func (c *Client) NotificationShadowEnabled() bool { + return c.notificationsShadow() +} + +// NotificationShadowRecords returns the bounded would-notify log, oldest +// first. +func (c *Client) NotificationShadowRecords() []NotificationShadowRecord { + if c == nil { + return nil + } + s := &c.notificationShadow + s.mu.Lock() + defer s.mu.Unlock() + out := make([]NotificationShadowRecord, 0, len(s.log)) + out = append(out, s.log[s.next:]...) + out = append(out, s.log[:s.next]...) + return out +} + +// notificationShadowLogAttrs are the shadow totals appended to the hourly +// "github notifications" line. Nil while shadow mode is off, so the line is +// unchanged. +func (c *Client) notificationShadowLogAttrs() []any { + if !c.notificationsShadow() { + return nil + } + totals := map[string]int64{} + for _, cnt := range c.NotificationShadowCounts() { + totals[cnt.Metric] += cnt.Value + } + return []any{ + "shadow_would_suppress", totals[NotificationMetricWouldSuppressRepeats], + "shadow_reviews", totals[NotificationMetricReviewsSubmitted], + "shadow_review_requests", totals[NotificationMetricReviewRequests], + "shadow_mentions", totals[NotificationMetricMentions], + "shadow_delivery_failures", totals[NotificationMetricDeliveryFailures], + "shadow_active_items", c.NotificationShadowActiveItems(), + } +} + +// mentionLoginRe matches a GitHub @-mention: an @ not preceded by a word +// character (so e-mail addresses do not count), then a login. +var mentionLoginRe = regexp.MustCompile(`(?:^|[^\w@/.-])@([A-Za-z0-9](?:[A-Za-z0-9-]{0,38})(?:/[A-Za-z0-9_.-]+)?)`) + +// extractMentionLogins returns the distinct logins (or org/team slugs) +// @-mentioned in body, in order of first appearance. +func extractMentionLogins(body string) []string { + if !strings.Contains(body, "@") { + return nil + } + var out []string + seen := map[string]bool{} + for _, m := range mentionLoginRe.FindAllStringSubmatch(body, -1) { + login := strings.ToLower(m[1]) + if !seen[login] { + seen[login] = true + out = append(out, login) + } + } + return out +} + +// attributeNotificationWrite walks the caller's stack to the first +// inventoried producer. Passthrough wrappers (CreateIssueCommentBudgeted, +// PostNoteOrFold, forge routers) are skipped in favour of their caller; if +// no producer is found the outermost passthrough seen is used, and failing +// that the write is "unknown"/unclassified. +func attributeNotificationWrite() (string, NotificationWriteSite) { + var pcs [64]uintptr + n := runtime.Callers(2, pcs[:]) + frames := runtime.CallersFrames(pcs[:n]) + fallback := "" + var fallbackSite NotificationWriteSite + for { + f, more := frames.Next() + name := notificationProducerName(f.Function) + if site, ok := notificationWriteSites[name]; ok { + if !site.Passthrough { + return name, site + } + fallback, fallbackSite = name, site + } + if !more { + break + } + } + if fallback != "" { + return fallback, fallbackSite + } + return "unknown", NotificationWriteSite{Class: NotificationClassUnclassified} +} + +// notificationProducerName turns a runtime function name +// ("github.com/hivecommons/hive/pkg/github.(*Client).foo.func1") into the +// inventory key ("github.(*Client).foo"): package name, receiver, function, +// with generic instantiations and closure suffixes removed. +func notificationProducerName(fn string) string { + for { + i := strings.IndexByte(fn, '[') + if i < 0 { + break + } + j := strings.IndexByte(fn[i:], ']') + if j < 0 { + break + } + fn = fn[:i] + fn[i+j+1:] + } + if i := strings.LastIndexByte(fn, '/'); i >= 0 { + fn = fn[i+1:] + } + parts := strings.Split(fn, ".") + for len(parts) > 2 && isClosureNamePart(parts[len(parts)-1]) { + parts = parts[:len(parts)-1] + } + return strings.Join(parts, ".") +} + +func isClosureNamePart(p string) bool { + for _, prefix := range []string{"func", "gowrap", "deferwrap"} { + if rest, ok := strings.CutPrefix(p, prefix); ok && rest != "" && isDigits(rest) { + return true + } + } + return p != "" && isDigits(p) +} + +func isDigits(s string) bool { + for _, r := range s { + if r < '0' || r > '9' { + return false + } + } + return s != "" +} diff --git a/src/pkg/github/notification_shadow_test.go b/src/pkg/github/notification_shadow_test.go new file mode 100644 index 0000000000..014fadf13b --- /dev/null +++ b/src/pkg/github/notification_shadow_test.go @@ -0,0 +1,180 @@ +package github + +import ( + "bytes" + "context" + "encoding/json" + "io" + "log/slog" + "net/http" + "net/http/httptest" + "strconv" + "strings" + "sync" + "testing" +) + +// writeRecorder is a GitHub stub that answers every read with an empty list +// and records every write (method, path and exact body bytes). +type writeRecorder struct { + mu sync.Mutex + writes []string +} + +func (w *writeRecorder) start(t *testing.T) *httptest.Server { + t.Helper() + srv := httptest.NewServer(http.HandlerFunc(func(rw http.ResponseWriter, r *http.Request) { + rw.Header().Set("Content-Type", "application/json") + if r.Method == http.MethodGet { + _, _ = rw.Write([]byte("[]")) + return + } + body, _ := io.ReadAll(r.Body) + w.mu.Lock() + w.writes = append(w.writes, r.Method+" "+r.URL.Path+" "+string(body)) + n := len(w.writes) + w.mu.Unlock() + rw.WriteHeader(http.StatusCreated) + _ = json.NewEncoder(rw).Encode(map[string]any{"id": n, "html_url": "https://example.test/c/" + r.URL.Path}) + })) + t.Cleanup(srv.Close) + return srv +} + +// runShadowScenario drives a fixed mix of notification-capable writes: +// a status note posted for two causes (the second a repeat of the same +// condition), a claim marker twice (protocol command), a review request, +// and a direct comment with @-mentions. +func runShadowScenario(t *testing.T, shadow bool) (*Client, []string) { + t.Helper() + rec := &writeRecorder{} + srv := rec.start(t) + c := testClient(t, srv.URL) + c.SetNotificationsShadow(func() bool { return shadow }) + ctx := context.Background() + logger := slog.New(slog.NewTextHandler(io.Discard, nil)) + + c.postUnblockedNote(ctx, "o/r", 5, blockedUnblockedMarker+"\nUnblocked: o/r#9 is no longer open.", logger) + c.postUnblockedNote(ctx, "o/r", 5, blockedUnblockedMarker+"\nUnblocked: o/r#12 is no longer open.", logger) + for i := 0; i < 2; i++ { + if err := c.PostClaimNote(ctx, "o/r", 6, "\nClaimed "+strconv.Itoa(i)); err != nil { + t.Fatalf("claim note: %v", err) + } + } + if err := c.RequestReviewers(ctx, "o/r", 7, []string{"alice"}, nil); err != nil { + t.Fatalf("request reviewers: %v", err) + } + if err := c.CreateIssueComment(ctx, "o/r", 8, "ping @alice and @bob"); err != nil { + t.Fatalf("comment: %v", err) + } + rec.mu.Lock() + defer rec.mu.Unlock() + return c, append([]string(nil), rec.writes...) +} + +// Shadow off and shadow on produce byte-for-byte the same GitHub writes; +// shadow off records nothing. +func TestNotificationShadowDoesNotChangeWrites(t *testing.T) { + off, offWrites := runShadowScenario(t, false) + _, onWrites := runShadowScenario(t, true) + if len(offWrites) == 0 { + t.Fatal("scenario made no writes") + } + if strings.Join(offWrites, "\n") != strings.Join(onWrites, "\n") { + t.Fatalf("writes differ with shadow on:\noff:\n%s\non:\n%s", strings.Join(offWrites, "\n"), strings.Join(onWrites, "\n")) + } + if got := off.NotificationShadowCounts(); len(got) != 0 { + t.Fatalf("shadow off recorded counters: %+v", got) + } + if got := off.NotificationShadowRecords(); len(got) != 0 { + t.Fatalf("shadow off recorded would-notify records: %+v", got) + } + if off.NotificationShadowActiveItems() != 0 { + t.Fatal("shadow off counted active items") + } +} + +// Shadow on: every write is attributed, classified and counted; a repeat +// of a status condition is would-suppress, a repeated protocol command is +// not; no record carries a comment body. +func TestNotificationShadowRecordsDecisions(t *testing.T) { + c, _ := runShadowScenario(t, true) + counts := map[string]int64{} + for _, cnt := range c.NotificationShadowCounts() { + counts[cnt.Metric+"|"+cnt.Producer+"|"+string(cnt.Class)] += cnt.Value + } + want := map[string]int64{ + NotificationMetricCommentsCreated + "|github.(*Client).postUnblockedNote|status": 2, + NotificationMetricWouldSuppressRepeats + "|github.(*Client).postUnblockedNote|status": 1, + NotificationMetricCommentsCreated + "|github.(*Client).PostClaimNote|protocol_command": 2, + NotificationMetricReviewRequests + "|github.(*Client).RequestReviewers|required_review": 1, + } + for k, v := range want { + if counts[k] != v { + t.Errorf("counter %s = %d, want %d (all: %v)", k, counts[k], v, counts) + } + } + var mentions int64 + for k, v := range counts { + if strings.HasPrefix(k, NotificationMetricMentions+"|") { + mentions += v + } + if strings.HasPrefix(k, NotificationMetricWouldSuppressRepeats+"|") && !strings.HasSuffix(k, "|status") && !strings.HasSuffix(k, "|attention") { + t.Errorf("non-suppressible class marked would-suppress: %s", k) + } + } + if mentions != 2 { + t.Errorf("mentions = %d, want 2", mentions) + } + if got := c.NotificationShadowActiveItems(); got != 4 { + t.Errorf("active items = %d, want 4", got) + } + + records := c.NotificationShadowRecords() + if len(records) != 6 { + t.Fatalf("records = %d, want 6: %+v", len(records), records) + } + raw, _ := json.Marshal(records) + for _, secret := range []string{"Unblocked:", "hive:claim", "ping"} { + if bytes.Contains(raw, []byte(secret)) { + t.Fatalf("record leaked comment body text %q: %s", secret, raw) + } + } + if r := records[1]; r.WouldNotify || r.Reason != NotificationReasonRepeatCondition || r.ConditionKey != records[0].ConditionKey { + t.Errorf("repeat status note = %+v, want would-suppress on the same condition key as %+v", r, records[0]) + } + if r := records[3]; !r.WouldNotify || r.Class != NotificationClassProtocolCommand || r.Reason != NotificationReasonExemptRepeat { + t.Errorf("repeat claim marker = %+v, want delivered as exempt protocol command", r) + } + if r := records[4]; r.Kind != string(notificationWriteReviewRequest) || r.Class != NotificationClassRequiredReview || strings.Join(r.Logins, ",") != "alice" { + t.Errorf("review request = %+v", r) + } + if r := records[5]; strings.Join(r.Logins, ",") != "alice,bob" { + t.Errorf("mention logins = %v, want alice,bob", r.Logins) + } +} + +// A failed delivery is counted as such and never as a created comment. +func TestNotificationShadowDeliveryFailure(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(rw http.ResponseWriter, r *http.Request) { + rw.WriteHeader(http.StatusForbidden) + })) + t.Cleanup(srv.Close) + c := testClient(t, srv.URL) + c.SetNotificationsShadow(func() bool { return true }) + if err := c.CreateIssueComment(context.Background(), "o/r", 1, "x"); err == nil { + t.Fatal("want an error from a 403") + } + var failures, created int64 + for _, cnt := range c.NotificationShadowCounts() { + switch cnt.Metric { + case NotificationMetricDeliveryFailures: + failures += cnt.Value + case NotificationMetricCommentsCreated: + created += cnt.Value + } + } + if failures != 1 || created != 0 { + t.Fatalf("failures=%d created=%d, want 1 and 0", failures, created) + } +} diff --git a/src/pkg/github/notification_tally.go b/src/pkg/github/notification_tally.go index e7e700999e..d5d445def1 100644 --- a/src/pkg/github/notification_tally.go +++ b/src/pkg/github/notification_tally.go @@ -31,18 +31,19 @@ type notificationTally struct { // notificationTallyNow is the tally's clock, replaced by tests. var notificationTallyNow = time.Now -func (t *notificationTally) bump(counter *atomic.Int64, logger *slog.Logger) { +func (t *notificationTally) bump(counter *atomic.Int64, logger *slog.Logger, extra ...any) { if t == nil { return } counter.Add(1) - t.maybeLog(logger) + t.maybeLog(logger, extra...) } // maybeLog writes the hourly line when at least notificationTallyLogEvery // has passed since the last one. The first bump after start logs at once -// so a fresh process reports its baseline. -func (t *notificationTally) maybeLog(logger *slog.Logger) { +// so a fresh process reports its baseline. extra carries the shadow-mode +// totals (github.notifications.shadow) and is empty while shadow is off. +func (t *notificationTally) maybeLog(logger *slog.Logger, extra ...any) { if logger == nil { return } @@ -56,10 +57,12 @@ func (t *notificationTally) maybeLog(logger *slog.Logger) { if !due { return } - logger.Info("github notifications", + args := []any{ slog.Int64("created", t.created.Load()), slog.Int64("edited", t.edited.Load()), - slog.Int64("suppressed", t.suppressed.Load())) + slog.Int64("suppressed", t.suppressed.Load()), + } + logger.Info("github notifications", append(args, extra...)...) } // noteCommentCreated records a new issue/PR comment. @@ -67,7 +70,7 @@ func (c *Client) noteCommentCreated() { if c == nil { return } - c.notifications.bump(&c.notifications.created, c.logger) + c.notifications.bump(&c.notifications.created, c.logger, c.notificationShadowLogAttrs()...) } // noteCommentEdited records an in-place comment edit. @@ -75,7 +78,7 @@ func (c *Client) noteCommentEdited() { if c == nil { return } - c.notifications.bump(&c.notifications.edited, c.logger) + c.notifications.bump(&c.notifications.edited, c.logger, c.notificationShadowLogAttrs()...) } // noteCommentSuppressed records a comment the hive chose not to create. @@ -83,7 +86,8 @@ func (c *Client) noteCommentSuppressed() { if c == nil { return } - c.notifications.bump(&c.notifications.suppressed, c.logger) + c.noteShadowSuppressed() + c.notifications.bump(&c.notifications.suppressed, c.logger, c.notificationShadowLogAttrs()...) } // NotificationCounts returns the cumulative created/edited/suppressed diff --git a/src/pkg/github/notification_write_sites.go b/src/pkg/github/notification_write_sites.go new file mode 100644 index 0000000000..3b9fef4da9 --- /dev/null +++ b/src/pkg/github/notification_write_sites.go @@ -0,0 +1,117 @@ +package github + +// NotificationWriteSite is the classification of one producer of +// notification-capable GitHub writes. +type NotificationWriteSite struct { + Class NotificationClass + // Passthrough marks a wrapper that forwards its caller's write; the + // shadow attribution looks past it to the caller and falls back to it + // only when the caller is not inventoried. + Passthrough bool +} + +// notificationWriteSites is the inventory of every function under src/pkg +// and src/cmd that calls a notification-capable write primitive +// (CreateIssueComment, CreateIssueCommentBudgeted, PostNoteOrFold, +// PostClaimNote, PullRequests.CreateReview, RequestReviewers) or records a +// suppressed note. Keys are "." or +// ".(*Recv).", the form runtime reports with closures +// stripped. TestNotificationWriteSitesInventory fails when a new call site +// is added without an entry here, so every write carries a class tag. The +// same table is documented in src/docs/notifications.md. +var notificationWriteSites = map[string]NotificationWriteSite{ + // Passthrough wrappers. + "github.(*Client).CreateIssueCommentBudgeted": {Class: NotificationClassStatus, Passthrough: true}, + "github.(*Client).PostNoteOrFold": {Class: NotificationClassStatus, Passthrough: true}, + "github.(*Client).RequestReviewers": {Class: NotificationClassRequiredReview, Passthrough: true}, + "main.(*repoForgeRouter).CreateIssueComment": {Class: NotificationClassAttention, Passthrough: true}, + "main.liveTriageCommenter.CreateIssueComment": {Class: NotificationClassAttention, Passthrough: true}, + "github.(*Client).UpsertIssueMarkerComment": {Class: NotificationClassStatus, Passthrough: true}, + + // status: bookkeeping readable on demand. + "dashboard.(*ContributeWSHub).markAlreadyDoneIssue": {Class: NotificationClassStatus}, + "dashboard.(*ContributeWSHub).releaseGateParkLabel": {Class: NotificationClassStatus}, + "dashboard.(*ContributeWSHub).releaseToolingBlockedLabel": {Class: NotificationClassStatus}, + "dashboard.(*Server).armRebaseThenMerge": {Class: NotificationClassStatus}, + "dashboard.(*Server).executeDelegatedDecision": {Class: NotificationClassStatus}, + "dashboard.(*Server).handlePullRequestMergeDecision": {Class: NotificationClassStatus}, + "dashboard.(*Server).handleRepoItemAdoptNow": {Class: NotificationClassStatus}, + "dashboard.(*Server).handleRepoItemBlockerClosePartial": {Class: NotificationClassStatus}, + "dashboard.(*Server).handleRepoItemDecision": {Class: NotificationClassStatus}, + "dashboard.(*Server).handleReviewQueueSupersededClose": {Class: NotificationClassStatus}, + "dashboard.(*Server).mirrorPlanWith": {Class: NotificationClassStatus}, + "github.(*Client).CloseIssueForConfiguredLinePR": {Class: NotificationClassStatus}, + "github.(*Client).PostFleetReportCleared": {Class: NotificationClassStatus}, + "github.(*Client).PostFleetReportRecovery": {Class: NotificationClassStatus}, + "github.(*Client).PostFleetReportRollup": {Class: NotificationClassStatus}, + "github.(*Client).SweepLegacyFleetReportIssues": {Class: NotificationClassStatus}, + "github.(*Client).closeDecomposedParent": {Class: NotificationClassStatus}, + "github.(*Client).closeIssueForMergedPRClaimWithIssue": {Class: NotificationClassStatus}, + "github.(*Client).closeSupersededPRDecision": {Class: NotificationClassStatus}, + "github.(*Client).fileReviewBacklog": {Class: NotificationClassStatus}, + "github.(*Client).joinFleetReportIssue": {Class: NotificationClassStatus}, + "github.(*Client).markInProgressStarted": {Class: NotificationClassStatus}, + "github.(*Client).postUnblockedNote": {Class: NotificationClassStatus}, + "github.(*Client).priorArtGateClose": {Class: NotificationClassStatus}, + "github.(*Client).reconcileBlockedTargets": {Class: NotificationClassStatus}, + "github.(*Client).recordReviewEvidenceMerge": {Class: NotificationClassStatus}, + "github.SyncIssueStageLabelsWith": {Class: NotificationClassStatus}, + "github.ensureIssueStagePRLink": {Class: NotificationClassStatus}, + "github.githubIssueBacklogSink.AppendToItem": {Class: NotificationClassStatus}, + "github.githubIssueBacklogSink.CloseItem": {Class: NotificationClassStatus}, + "github.githubIssueBacklogSink.LiftBlock": {Class: NotificationClassStatus}, + "github.handleMergedPRIssueStage": {Class: NotificationClassStatus}, + "github.runRecheckSoak": {Class: NotificationClassStatus}, + "main.postReviewAcknowledgements": {Class: NotificationClassStatus}, + "main.rfcNotifySource.Comment": {Class: NotificationClassStatus}, + "main.unparkEscalatedPR": {Class: NotificationClassStatus}, + + // attention: asks a person to look or act. + "dashboard.(*ContributeWSHub).parkWrongBase": {Class: NotificationClassAttention}, + "dashboard.(*Server).handleRepoItemReroute": {Class: NotificationClassAttention}, + "dashboard.(*Server).handleReviewPipelineSendToHuman": {Class: NotificationClassAttention}, + "dashboard.(*Server).reroutePickupLapsed": {Class: NotificationClassAttention}, + "dashboard.(*Server).settleRebaseMergeLedger": {Class: NotificationClassAttention}, + "github.(*Client).NudgeTrackingIssueClosingRefs": {Class: NotificationClassAttention}, + "github.(*Client).appendFoldedFinding": {Class: NotificationClassAttention}, + "github.(*Client).bindProwLgtm": {Class: NotificationClassAttention}, + "github.(*Client).commentOnHumanFiledTwin": {Class: NotificationClassAttention}, + "github.(*Client).createIssue": {Class: NotificationClassAttention}, + "github.(*Client).handleOneIssueRequest": {Class: NotificationClassAttention}, + "github.(*Client).parkClankerRequestedPR": {Class: NotificationClassAttention}, + "github.(*Client).redirectToExistingPR": {Class: NotificationClassAttention}, + "github.(*Client).resolveDuplicateFixGroup": {Class: NotificationClassAttention}, + "main.claimEscalationLookup": {Class: NotificationClassAttention}, + "main.maintainHeldPRMergeability": {Class: NotificationClassAttention}, + "main.rfcCoverageForge.CreateComment": {Class: NotificationClassAttention}, + "main.runEscalationSweep": {Class: NotificationClassAttention}, + "prfollowup.postStaleHeadPushNotes": {Class: NotificationClassAttention}, + "scheduler.(*Scheduler).judgePriorArt": {Class: NotificationClassAttention}, + "scheduler.(*Scheduler).parkUnclearIssue": {Class: NotificationClassAttention}, + "scheduler.(*Scheduler).postTriageClarifyComment": {Class: NotificationClassAttention}, + + // required_review: a review submission or request a merge depends on. + "github.(*Client).QueuePRAutoMergeWithNoteResult": {Class: NotificationClassRequiredReview}, + "github.(*Client).handleOneReviewRequest": {Class: NotificationClassRequiredReview}, + + // protocol_command: machine-consumed comments. + "dashboard.postClaimComment": {Class: NotificationClassProtocolCommand}, + "github.(*Client).PostClaimNote": {Class: NotificationClassProtocolCommand}, + "github.(*Client).RecordOperatorPullRequestApprovalWith": {Class: NotificationClassProtocolCommand}, + "main.githubClaimHooks": {Class: NotificationClassProtocolCommand}, + + // security_event: trust and integrity signals. + "github.(*Client).handleOnePRRequest": {Class: NotificationClassSecurityEvent}, + "github.(*Client).markReporterTrustAwaiting": {Class: NotificationClassSecurityEvent}, + "github.(*Client).reconcileReporterTrustSignal": {Class: NotificationClassSecurityEvent}, + "main.enforceHoldGuard": {Class: NotificationClassSecurityEvent}, +} + +// NotificationWriteSites returns a copy of the write-site inventory. +func NotificationWriteSites() map[string]NotificationWriteSite { + out := make(map[string]NotificationWriteSite, len(notificationWriteSites)) + for k, v := range notificationWriteSites { + out[k] = v + } + return out +} diff --git a/src/pkg/github/notification_write_sites_test.go b/src/pkg/github/notification_write_sites_test.go new file mode 100644 index 0000000000..44d6086706 --- /dev/null +++ b/src/pkg/github/notification_write_sites_test.go @@ -0,0 +1,187 @@ +package github + +import ( + "go/ast" + "go/parser" + "go/token" + "io/fs" + "path/filepath" + "sort" + "strings" + "testing" +) + +// notificationWritePrimitives are the method names whose call sites must be +// inventoried in notificationWriteSites. +var notificationWritePrimitives = map[string]bool{ + "CreateIssueComment": true, + "CreateIssueCommentBudgeted": true, + "PostNoteOrFold": true, + "PostClaimNote": true, + "CreateReview": true, + "RequestReviewers": true, + "noteCommentSuppressed": true, +} + +// TestNotificationWriteSitesInventory is the class-tag guard +// (hivecommons/hive#16264): every non-test function under src/pkg and +// src/cmd that calls a notification-capable write primitive must have an +// entry in notificationWriteSites, and every entry must still name such a +// function. Add the new producer to the inventory (and to the table in +// src/docs/notifications.md) with its class. +func TestNotificationWriteSitesInventory(t *testing.T) { + found := map[string]string{} + fset := token.NewFileSet() + for _, root := range []string{"..", filepath.Join("..", "..", "cmd")} { + err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error { + if err != nil { + return err + } + if d.IsDir() { + switch d.Name() { + case "testdata", "vendor", "node_modules": + return filepath.SkipDir + } + return nil + } + if !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") { + return nil + } + f, perr := parser.ParseFile(fset, path, nil, parser.SkipObjectResolution) + if perr != nil { + return perr + } + for _, decl := range f.Decls { + var name string + var body ast.Node + switch d := decl.(type) { + case *ast.FuncDecl: + if d.Body == nil { + continue + } + name, body = f.Name.Name+"."+funcDeclProducerName(d), d.Body + case *ast.GenDecl: + name, body = f.Name.Name+".", d + } + if body == nil { + continue + } + ast.Inspect(body, func(n ast.Node) bool { + call, ok := n.(*ast.CallExpr) + if !ok { + return true + } + sel, ok := call.Fun.(*ast.SelectorExpr) + if ok && notificationWritePrimitives[sel.Sel.Name] { + if _, dup := found[name]; !dup { + found[name] = fset.Position(call.Pos()).String() + } + } + return true + }) + } + return nil + }) + if err != nil { + t.Fatalf("walking %s: %v", root, err) + } + } + if len(found) == 0 { + t.Fatal("found no notification write call sites; is the walk rooted correctly?") + } + var missing, stale []string + for name, pos := range found { + if _, ok := notificationWriteSites[name]; !ok { + missing = append(missing, name+" ("+pos+")") + } + } + for name, site := range notificationWriteSites { + if _, ok := found[name]; !ok { + stale = append(stale, name) + } + switch site.Class { + case NotificationClassStatus, NotificationClassAttention, NotificationClassRequiredReview, + NotificationClassProtocolCommand, NotificationClassSecurityEvent: + default: + t.Errorf("%s: invalid class %q", name, site.Class) + } + } + sort.Strings(missing) + sort.Strings(stale) + for _, m := range missing { + t.Errorf("notification-capable write without a class tag: %s — add it to notificationWriteSites and src/docs/notifications.md", m) + } + for _, s := range stale { + t.Errorf("notificationWriteSites entry %s no longer calls a write primitive; remove it", s) + } +} + +// funcDeclProducerName renders d the way runtime names it: +// "F", "T.M" or "(*T).M". +func funcDeclProducerName(d *ast.FuncDecl) string { + if d.Recv == nil || len(d.Recv.List) == 0 { + return d.Name.Name + } + typ := d.Recv.List[0].Type + star := false + if s, ok := typ.(*ast.StarExpr); ok { + star, typ = true, s.X + } + switch g := typ.(type) { + case *ast.IndexExpr: + typ = g.X + case *ast.IndexListExpr: + typ = g.X + } + recv := "?" + if id, ok := typ.(*ast.Ident); ok { + recv = id.Name + } + if star { + return "(*" + recv + ")." + d.Name.Name + } + return recv + "." + d.Name.Name +} + +// Protocol commands, required reviews and security events are never +// would-suppress candidates. +func TestNotificationClassSuppressible(t *testing.T) { + for class, want := range map[NotificationClass]bool{ + NotificationClassStatus: true, + NotificationClassAttention: true, + NotificationClassRequiredReview: false, + NotificationClassProtocolCommand: false, + NotificationClassSecurityEvent: false, + NotificationClassUnclassified: false, + } { + if got := class.Suppressible(); got != want { + t.Errorf("%s.Suppressible() = %v, want %v", class, got, want) + } + } +} + +func TestNotificationProducerName(t *testing.T) { + for in, want := range map[string]string{ + "github.com/hivecommons/hive/pkg/github.(*Client).PostNoteOrFold": "github.(*Client).PostNoteOrFold", + "github.com/hivecommons/hive/pkg/github.(*Client).handleOneIssueRequest.func2": "github.(*Client).handleOneIssueRequest", + "github.com/hivecommons/hive/pkg/github.runRecheckSoak.func1.3": "github.runRecheckSoak", + "main.githubClaimHooks.func4.1": "main.githubClaimHooks", + "main.liveTriageCommenter.CreateIssueComment": "main.liveTriageCommenter.CreateIssueComment", + "github.com/hivecommons/hive/pkg/x.F[...]": "x.F", + } { + if got := notificationProducerName(in); got != want { + t.Errorf("notificationProducerName(%q) = %q, want %q", in, got, want) + } + } +} + +func TestExtractMentionLogins(t *testing.T) { + got := extractMentionLogins("cc @Alice and @bob-2, again @alice; mail me at x@example.com; team @org/team\n@carol") + want := []string{"alice", "bob-2", "org/team", "carol"} + if strings.Join(got, ",") != strings.Join(want, ",") { + t.Fatalf("mentions = %v, want %v", got, want) + } + if extractMentionLogins("no mentions here") != nil { + t.Fatal("want no mentions") + } +} diff --git a/src/pkg/github/pr_status_comment.go b/src/pkg/github/pr_status_comment.go index e1ea1587dc..49bfe1eb78 100644 --- a/src/pkg/github/pr_status_comment.go +++ b/src/pkg/github/pr_status_comment.go @@ -45,7 +45,7 @@ func (c *Client) PostNoteOrFold(ctx context.Context, repo string, number int, ke return false, ErrNoGitHubClient } if !c.notificationsQuiet() { - return true, c.CreateIssueComment(ctx, repo, number, body) + return true, c.CreateIssueComment(WithNotificationSubject(ctx, key), repo, number, body) } created, err := c.UpsertPRStatusSection(ctx, repo, number, key, body) if err == nil && !created { diff --git a/src/pkg/github/review_request_watcher.go b/src/pkg/github/review_request_watcher.go index 6c4204de0d..ea582bb3de 100644 --- a/src/pkg/github/review_request_watcher.go +++ b/src/pkg/github/review_request_watcher.go @@ -548,6 +548,7 @@ func (c *Client) handleOneReviewRequest(ctx context.Context, path string, src re var created *gh.PullRequestReview decisionDeduped := false ownPRNote := "" + reviewSubmitted := false if leak, ok := c.scanCanaryText(req.Body, "hive-review:"+req.Repo); ok && c.canaryFailClosed { err = fmt.Errorf("ioscan canary leak detected: agent=%s source=%s", leak.Agent, leak.Source) } else if req.Revise { @@ -557,6 +558,7 @@ func (c *Client) handleOneReviewRequest(ctx context.Context, path string, src re var revised bool created, revised, err = c.reviseReview(ctx, req, body) if err == nil && created == nil && !revised { + reviewSubmitted = true created, _, err = c.client.PullRequests.CreateReview(ctx, owner, repoName, req.Number, reviewReq) } } else if existing := c.findOwnOpenDecisionReview(ctx, owner, repoName, req.Number, req.Body); existing != nil && apiEvent == "COMMENT" { @@ -569,6 +571,7 @@ func (c *Client) handleOneReviewRequest(ctx context.Context, path string, src re decisionDeduped = true } } else { + reviewSubmitted = true provenance := owner + "/" + repoName + "#" + strconv.Itoa(req.Number) _, err = effects.ExecuteReconciling(ctx, c.mutationBoundary(), effects.Claim{ Repo: owner + "/" + repoName, @@ -604,6 +607,9 @@ func (c *Client) handleOneReviewRequest(ctx context.Context, path string, src re } }) } + if reviewSubmitted { + c.recordNotificationWrite(ctx, notificationWrite{kind: notificationWriteReview, repo: owner + "/" + repoName, item: req.Number, body: body, class: NotificationClassRequiredReview, err: err}) + } if errors.Is(err, errReviseNotAllowlisted) { // Policy, not a transient fault (#13252): the repo is not in // review.revise_repos, and no retry changes that. Deny once and move From de063ccca5bbfe36ffcb1546100ddee4e6da8d88 Mon Sep 17 00:00:00 2001 From: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Mon, 2 Nov 2026 17:30:58 -0500 Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=93=9D=20docs:=20refresh=20scale-enve?= =?UTF-8?q?lope=20citation=20after=20client.go=20shift?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- 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 3dd2f95a60..fcd433653b 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:5040-5050`, descending `AgeMinutes` within each tier). + (`RankActionableIssues`, `src/pkg/github/client.go:5051-5061`, 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). From 1343093e3bfb9d9546588c83617b07eb7d6997ca Mon Sep 17 00:00:00 2001 From: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Mon, 2 Nov 2026 17:34:52 -0500 Subject: [PATCH 3/4] docs: refresh scale-envelope citation after v5 merge Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- 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 011690f25d..b49f26fa1f 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:5058-5068`, descending `AgeMinutes` within each tier). + (`RankActionableIssues`, `src/pkg/github/client.go:5068-5078`, 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). From 87d2118da21fa78f890ab4e491a8ad37cb5c09c4 Mon Sep 17 00:00:00 2001 From: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Mon, 2 Nov 2026 17:42:02 -0500 Subject: [PATCH 4/4] fix(notifications): track renamed write sites after v5 merge v5 renamed QueuePRAutoMergeWithNoteResult -> QueuePRAutoMergeWithNoteResultAtHead and moved the operator-approval write into reportOperatorPullRequestApproval, so TestNotificationWriteSitesInventory flagged both as drift. Update the inventory and the docs table to the new symbol names. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- src/docs/notifications.md | 4 ++-- src/pkg/github/notification_write_sites.go | 12 ++++++------ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/docs/notifications.md b/src/docs/notifications.md index eb3f9da9ee..61e4a03764 100644 --- a/src/docs/notifications.md +++ b/src/docs/notifications.md @@ -416,12 +416,12 @@ without a class. Review submissions and review requests are always counted as | `scheduler.(*Scheduler).judgePriorArt` | `attention` | | | `scheduler.(*Scheduler).parkUnclearIssue` | `attention` | | | `scheduler.(*Scheduler).postTriageClarifyComment` | `attention` | | -| `github.(*Client).QueuePRAutoMergeWithNoteResult` | `required_review` | | +| `github.(*Client).QueuePRAutoMergeWithNoteResultAtHead` | `required_review` | | | `github.(*Client).RequestReviewers` | `required_review` | passthrough wrapper; attributed to its caller | | `github.(*Client).handleOneReviewRequest` | `required_review` | | | `dashboard.postClaimComment` | `protocol_command` | | | `github.(*Client).PostClaimNote` | `protocol_command` | | -| `github.(*Client).RecordOperatorPullRequestApprovalWith` | `protocol_command` | | +| `github.(*Client).reportOperatorPullRequestApproval` | `protocol_command` | | | `main.githubClaimHooks` | `protocol_command` | | | `github.(*Client).handleOnePRRequest` | `security_event` | | | `github.(*Client).markReporterTrustAwaiting` | `security_event` | | diff --git a/src/pkg/github/notification_write_sites.go b/src/pkg/github/notification_write_sites.go index 3b9fef4da9..b764528475 100644 --- a/src/pkg/github/notification_write_sites.go +++ b/src/pkg/github/notification_write_sites.go @@ -91,14 +91,14 @@ var notificationWriteSites = map[string]NotificationWriteSite{ "scheduler.(*Scheduler).postTriageClarifyComment": {Class: NotificationClassAttention}, // required_review: a review submission or request a merge depends on. - "github.(*Client).QueuePRAutoMergeWithNoteResult": {Class: NotificationClassRequiredReview}, - "github.(*Client).handleOneReviewRequest": {Class: NotificationClassRequiredReview}, + "github.(*Client).QueuePRAutoMergeWithNoteResultAtHead": {Class: NotificationClassRequiredReview}, + "github.(*Client).handleOneReviewRequest": {Class: NotificationClassRequiredReview}, // protocol_command: machine-consumed comments. - "dashboard.postClaimComment": {Class: NotificationClassProtocolCommand}, - "github.(*Client).PostClaimNote": {Class: NotificationClassProtocolCommand}, - "github.(*Client).RecordOperatorPullRequestApprovalWith": {Class: NotificationClassProtocolCommand}, - "main.githubClaimHooks": {Class: NotificationClassProtocolCommand}, + "dashboard.postClaimComment": {Class: NotificationClassProtocolCommand}, + "github.(*Client).PostClaimNote": {Class: NotificationClassProtocolCommand}, + "github.(*Client).reportOperatorPullRequestApproval": {Class: NotificationClassProtocolCommand}, + "main.githubClaimHooks": {Class: NotificationClassProtocolCommand}, // security_event: trust and integrity signals. "github.(*Client).handleOnePRRequest": {Class: NotificationClassSecurityEvent},