refactor(flowcontrol): scrub shard vocabulary and rewrite docs to single-processor model

Post-llm-d#889 the flow control layer is single-processor, but the package/type docs and many
comments/log strings/test names still described the old sharded supervisor-worker-pool design
(and referenced deleted types like RegistryShard/ShardProcessor). Rename the vestigial 'shard'
vocabulary to match reality (sp->p receiver, log/error strings, comments, test names), rewrite
the doc.go files and stale type docs to the single-processor model, make doc.go the single
source of truth for the controller package architecture, correct the wrong distributeRequest
and managedQueue.Add docstrings, and drop the one-use flowComponents wrapper. No behavior change.

Refs: llm-d#889
Signed-off-by: Luke Van Drie <lukevandrie@google.com>

Author: LukeAVanDrie

pkg/epp/flowcontrol/controller/controller.go

@@ -14,11 +14,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// Package controller contains the implementation of the FlowController engine.
-//
-// The FlowController is the central processing engine of the Flow Control layer. It is a high-throughput
-// component responsible for managing the lifecycle of all incoming requests. It achieves this by acting as a stateless
-// supervisor that orchestrates a stateful worker (Processor).
 package controller
 
 import (
@@ -46,7 +41,7 @@ type registryClient interface {
 	contracts.FlowRegistryDataPlane
 }
 
-// processor is the minimal internal interface that the FlowController requires from its workers.
+// processor is the minimal internal interface that the FlowController requires from its worker.
 type processor interface {
 	Run(ctx context.Context)
 	Submit(item *internal.FlowItem) error
@@ -70,8 +65,8 @@ type processorFactory func(
 var _ processor = &internal.Processor{}
 
 // FlowController is the central, high-throughput engine of the Flow Control layer.
-// It is designed as a stateless distributor that orchestrates a stateful worker (Processor), following a
-// supervisor-worker pattern.
+// It is the request-facing front end that hands each request to a single stateful worker (the Processor) and blocks
+// until the request reaches a terminal outcome.
 //
 // Request Lifecycle Management:
 //
@@ -334,7 +329,7 @@ func (fc *FlowController) withConnectionWithFallback(
 	})
 }
 
-// tryDistribution handles a single attempt to select a shard and submit a request.
+// tryDistribution handles a single attempt to submit a request to the processor.
 // It uses the provided `conn` to access the registry data plane.
 // If this function returns an error, it guarantees that the provided `item` has been finalized.
 func (fc *FlowController) tryDistribution(
@@ -426,21 +421,19 @@ func (fc *FlowController) createRequestContext(
 	return reqCtx, cancel, enqueueTime
 }
 
-// distributeRequest implements a flow-aware, two-phase "Join-Shortest-Queue-by-Bytes" (JSQ-Bytes) distribution strategy
-// with graceful backpressure. It attempts to submit an item to the best-ranked candidate from the provided list.
+// distributeRequest submits an item to the processor with graceful backpressure.
 //
-// The algorithm operates as follows:
-//  1. Phase 1 (Non-blocking Fast Failover): It iterates through the ranked candidates and attempts a non-blocking
-//     submission. The first successful submission wins.
-//  2. Phase 2 (Blocking Fallback): If all non-blocking attempts fail, it performs a single blocking submission to the
-//     least-loaded candidate, providing backpressure.
+// It operates in two phases:
+//  1. Non-blocking submit: a fast Submit that succeeds immediately if the processor's enqueue channel has capacity.
+//  2. Blocking fallback: if the processor is busy, a single blocking SubmitOrBlock that applies backpressure until the
+//     item is accepted, the context expires, or the processor shuts down.
 //
 // The provided context (ctx) is used for the blocking submission phase (SubmitOrBlock).
 //
 // Ownership Contract:
-//   - Returns nil: Success. Ownership transferred to Processor.
-//   - Returns error: Failure (Context expiry, shutdown,, etc.).
-//     Ownership retained by Controller. The Controller MUST finalize the item.
+//   - Returns nil: Success. Ownership transferred to the Processor.
+//   - Returns error: Failure (context expiry, shutdown, etc.).
+//     Ownership retained by the Controller, which MUST finalize the item.
 func (fc *FlowController) distributeRequest(
 	ctx context.Context,
 	item *internal.FlowItem,

pkg/epp/flowcontrol/controller/doc.go

@@ -18,30 +18,29 @@ limitations under the License.
 //
 // # Overview
 //
-// The FlowController is the central processing engine of the Flow Control layer. It acts as a stateless supervisor that
-// orchestrates a pool of stateful workers (internal.ShardProcessor), managing the lifecycle of all incoming requests
-// from initial submission to a terminal outcome (dispatch, rejection, or eviction).
+// The FlowController is the central processing engine of the Flow Control layer. It manages the lifecycle of all
+// incoming requests from initial submission to a terminal outcome (dispatch, rejection, or eviction).
 //
-// # Architecture: Supervisor-Worker Pattern
+// # Architecture
 //
-// This package implements a supervisor-worker pattern to achieve high throughput and dynamic scalability.
+// The engine is split into two cooperating roles:
 //
-//   - The FlowController (Supervisor): The public-facing API of the system. Its primary responsibilities are to execute
-//     a distribution algorithm to select the optimal worker for a new request and to manage the lifecycle of the worker
-//     pool, ensuring it stays synchronized with the underlying shard topology defined by the contracts.FlowRegistry.
-//   - The internal.ShardProcessor (Worker): A stateful, single-goroutine actor responsible for the entire lifecycle of
-//     requests on a single shard. The supervisor manages a pool of these workers, one for each contracts.RegistryShard.
+//   - The FlowController: The public-facing API of the system. Each call to EnqueueAndWait runs on its own (caller's)
+//     goroutine: it acquires a flow lease from the contracts.FlowRegistry, hands the request to the Processor, and
+//     blocks until the request is finalized. It owns asynchronous finalization driven by the request Context
+//     (TTL/cancellation) and queue occupancy metrics.
+//   - The internal.Processor (Worker): A single, stateful, single-goroutine actor that owns the request data plane. It
+//     runs the dispatch loop, performs capacity checks, sweeps externally finalized items, and finalizes requests
+//     synchronously (dispatch, capacity rejection, shutdown).
 //
 // # Concurrency Model
 //
-// The FlowController is designed to be highly concurrent and thread-safe. It acts primarily as a stateless distributor.
+// The FlowController is designed to be highly concurrent and thread-safe. This rests on two properties:
 //
-//   - EnqueueAndWait: Can be called concurrently by many goroutines.
-//   - Worker Management: Uses a sync.Map (workers) for concurrent access and lazy initialization of workers.
-//   - Supervision: A single background goroutine (run) manages the worker pool lifecycle (garbage collection).
-//
-// It achieves high throughput by minimizing shared state and relying on the internal ShardProcessors to handle state
-// mutations serially (using an actor model).
+//   - EnqueueAndWait: Can be called concurrently by many goroutines, each handing its item to the single Processor over
+//     a buffered channel.
+//   - Single-Writer Actor: Routing all state mutations through the Processor's single Run goroutine makes complex
+//     transactions (such as capacity checks) inherently atomic without coarse-grained locks.
 //
 // # Request Lifecycle and Ownership
 //

pkg/epp/flowcontrol/controller/internal/doc.go

@@ -22,15 +22,15 @@ limitations under the License.
 // # Design Philosophy: The Single-Writer Actor Model
 //
 // The concurrency model for this package is built around a single-writer, channel-based actor pattern, as implemented
-// in the ShardProcessor. All state-mutating operations for a given shard (primarily enqueuing new requests) are
-// funneled through a single Run goroutine.
+// in the Processor. All state-mutating operations (primarily enqueuing new requests) are funneled through a single Run
+// goroutine.
 //
-// This design makes complex, multi-step transactions (like a hierarchical capacity check against both a shard's total
+// This design makes complex, multi-step transactions (like a hierarchical capacity check against both the global total
 // limit and a priority band's limit) inherently atomic without locks. This avoids the performance bottleneck of a
-// coarse, shard-wide lock and allows the top-level Controller to remain decoupled and highly concurrent.
+// coarse, global lock and allows the top-level Controller to remain decoupled and highly concurrent.
 //
 // # Key Components
 //
-//   - ShardProcessor: The implementation of the worker actor. Manages the lifecycle of requests for a single shard.
+//   - Processor: The implementation of the worker actor. Manages the lifecycle of all queued requests.
 //   - FlowItem: The internal representation of a request, managing its state and synchronization across goroutines.
 package internal