chore(flowcontrol): document panic-free posture and enforce it with forbidigo

The package doc records why invariant panics are unnecessary and points
to the files that own the details. A forbidigo rule bans panic() in
pkg/epp/flowcontrol non-test files with no allowlist.

Signed-off-by: Luke Van Drie <lukevandrie@google.com>

Author: LukeAVanDrie

.golangci.yml

@@ -18,6 +18,7 @@ linters:
     - durationcheck
     - errcheck
     - fatcontext
+    - forbidigo
     - ginkgolinter
     - goconst
     - gocritic
@@ -53,7 +54,18 @@ linters:
           - goconst
           - dupword
           - prealloc
+      # The panic ban applies only to pkg/epp/flowcontrol (non-test files); see that package's doc.go.
+      - path-except: pkg/epp/flowcontrol/
+        linters:
+          - forbidigo
+      - path: _test\.go$
+        linters:
+          - forbidigo
   settings:
+    forbidigo:
+      forbid:
+        - pattern: ^panic$
+          msg: "pkg/epp/flowcontrol is panic-free by design (see its doc.go); validate at the boundary and return an error"
     importas:
       no-unaliased: false # unaliased imports are allowed; only enforce when an alias is used
       alias:

pkg/epp/flowcontrol/doc.go

@@ -0,0 +1,31 @@
+/*
+Copyright 2026 The llm-d Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Package flowcontrol wires the flow control system: the FlowController data plane and the
+// FlowRegistry control plane.
+//
+// The package tree is panic-free, enforced by a lint rule. Statistics have a single owner per
+// level, so there is no duplicated state for an invariant check to guard (see
+// registry/managedqueue.go and queue/priorityqueue.go); caller- and plugin-supplied values are
+// validated at the boundary and surfaced as errors; long-lived goroutines defer
+// utilruntime.HandleCrashWithLogger so an unknown bug is logged with component context before the
+// process exits. Recover-and-continue is not used: a goroutine that panicked mid-mutation cannot
+// prove its state is consistent.
+//
+// If SafeQueue ever becomes an injectable extension point again, queue-reported stats become
+// plugin output and accounting must move to booked-charge, settle-at-most-once validation at the
+// managedQueue boundary.
+package flowcontrol