docs: Update comments to align with FlowController

This commit updates documentation and code comments across various
framework components to align with the concepts and architecture
introduced by the `FlowController`.

Key changes include:

- FCFS Policy: Clarified the distinction between "logical" and
  "physical" enqueue time and the behavioral trade-offs when pairing
  with different queue capabilities.
- ListQueue: Expanded the documentation to explain its role as a
  high-performance, approximate FCFS queue in the context of the
  `FlowController`'s retry mechanics.
- Request Types: Refined the comments for `QueueItemAccessor` to be more
  precise about the meaning of `EnqueueTime`.

Author: LukeAVanDrie

pkg/epp/flowcontrol/framework/plugins/policies/intraflow/dispatch/fcfs/fcfs.go

@@ -26,6 +26,32 @@ import (
 )
 
 // FCFSPolicyName is the name of the FCFS policy implementation.
+//
+// This policy implements a First-Come, First-Served (FCFS) strategy by selecting the item with the earliest logical
+// enqueue time.
+//
+// # Behavior and Queue Pairing
+//
+// The behavioral guarantees of this policy are critically dependent on the capabilities of the `framework.SafeQueue` it
+// is paired with. The system distinguishes between:
+//   - "Logical Enqueue Time": The timestamp when a request first arrives at the `controller.FlowController`.
+//   - "Physical Enqueue Time": The timestamp when a request is added to a specific shard's queue, which happens later.
+//
+// This policy's behavior changes accordingly:
+//   - Paired with a `CapabilityPriorityConfigurable` queue, it provides strict FCFS ordering based on logical enqueue
+//     time, aligning with this policy's vended `framework.ItemComparator`.
+//     This configuration ensures that requests are processed in the order they arrived at the controller, providing the
+//     most intuitive behavior.
+//   - Paired with a `CapabilityFIFO` queue, it provides approximate FCFS ordering based on physical arrival order at
+//     the `framework.SafeQueue`.
+//     This configuration offers higher performance at the cost of strict logical-time ordering, as the
+//     `controller.FlowController`'s "bounce-and-retry" mechanic for Draining shards means a bounced request may be
+//     processed after a request that logically darrived later.
+//
+// Given that true end-to-end ordering is non-deterministic in a distributd system, this policy defaults to pairing with
+// a CapabilityFIFO` queue (like "ListQueue") to prioritize performance and high throughput. For users who require the
+// strictest possible logical-time ordering that this layer can provide, explicitly pairing this policy with a
+// `CapabilityPriorityConfigurable` queue is recommended.
 const FCFSPolicyName = "FCFS"
 
 func init() {
@@ -35,7 +61,9 @@ func init() {
 		})
 }
 
-// fcfs (First-Come, First-Served) implements the `framework.IntraFlowDispatchPolicy` interface.
+// fcfs is the internal implementation of the FCFS policy.
+// See the documentation for the exported `FCFSPolicyName` constant for detailed user-facing information about its
+// behavior.
 type fcfs struct {
 	comparator framework.ItemComparator
 }
@@ -70,9 +98,10 @@ func (p *fcfs) Comparator() framework.ItemComparator {
 	return p.comparator
 }
 
-// RequiredQueueCapabilities specifies that this policy needs a queue that supports FIFO operations.
+// RequiredQueueCapabilities returns an empty slice, indicating that this policy can operate with any queue.
+// See the `FCFSPolicyName` constant's documentation for details on the behavioral trade-offs.
 func (p *fcfs) RequiredQueueCapabilities() []framework.QueueCapability {
-	return []framework.QueueCapability{framework.CapabilityFIFO}
+	return []framework.QueueCapability{}
 }
 
 // --- enqueueTimeComparator ---

pkg/epp/flowcontrol/framework/plugins/policies/intraflow/dispatch/fcfs/fcfs_test.go

@@ -41,8 +41,7 @@ func TestFCFS_RequiredQueueCapabilities(t *testing.T) {
 	t.Parallel()
 	policy := newFCFS()
 	caps := policy.RequiredQueueCapabilities()
-	require.Len(t, caps, 1, "RequiredQueueCapabilities should return one capability")
-	assert.Equal(t, framework.CapabilityFIFO, caps[0], "Required capability should be FIFO")
+	require.Empty(t, caps, "No required capabilities should be returned")
 }
 
 func TestFCFS_SelectItem(t *testing.T) {

pkg/epp/flowcontrol/framework/plugins/queue/listqueue/listqueue.go

@@ -14,8 +14,8 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// Package listqueue provides a simple, concurrent-safe queue implementation using a standard library
-// `container/list.List` as the underlying data structure for FIFO (First-In, First-Out) behavior.
+// Package listqueue provides a high-performance, concurrent-safe FIFO (First-In, First-Out) implementation of
+// implementation of the `framework.SafeQueue` based on the standard library's `container/list`.
 package listqueue
 
 import (
@@ -28,7 +28,28 @@ import (
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/flowcontrol/types"
 )
 
-// ListQueueName is the name of the list queue implementation.
+// ListQueueName is the name of the list-based queue implementation.
+//
+// This queue provides a high-performance, low-overhead implementation based on a standard `container/list`.
+// It advertises the `CapabilityFIFO`.
+//
+// # Behavioral Guarantees
+//
+// The core guarantee of this queue is strict physical First-In, First-Out (FIFO) ordering. It processes items in the
+// exact order they are added to the queue on a specific shard.
+//
+// # Performance and Trade-offs
+//
+// Because the physical insertion order may not match a request's logical arrival time (due to the
+// `controller.FlowController`'s internal "bounce-and-retry" mechanic), this queue provides an*approximate FCFS behavior
+// from a system-wide perspective.
+//
+// Given that true end-to-end ordering is non-deterministic in a distributed system, this high-performance queue is the
+// recommended default for most FCFS-like policies. It prioritizes throughput and efficiency, which aligns with the
+// primary goal of the Flow Control system.
+//
+// For workloads that require the strictest possible logical-time ordering this layer can provide, explicitly using a
+// queue that supports `CapabilityPriorityConfigurable` is the appropriate choice.
 const ListQueueName = "ListQueue"
 
 func init() {
@@ -39,8 +60,8 @@ func init() {
 		})
 }
 
-// listQueue implements the `framework.SafeQueue` interface using a standard `container/list.List` for FIFO behavior.
-// This implementation is concurrent-safe.
+// listQueue is the internal implementation of the ListQueue.
+// See the documentation for the exported `ListQueueName` constant for detailed user-facing information.
 type listQueue struct {
 	requests *list.List
 	byteSize atomic.Uint64

pkg/epp/flowcontrol/registry/config_test.go

@@ -211,16 +211,26 @@ func TestConfig_NewConfig(t *testing.T) {
 			name: "ShouldError_WhenQueueFactoryFails",
 			input: Config{
 				PriorityBands: []PriorityBandConfig{{
-					Priority:     1,
-					PriorityName: "High",
-					Queue:        queue.RegisteredQueueName("failing-queue"),
+					Priority:                1,
+					PriorityName:            "High",
+					Queue:                   queue.RegisteredQueueName("failing-queue"),
+					IntraFlowDispatchPolicy: intra.RegisteredPolicyName("policy-with-req"),
 				}},
 			},
 			expectErr: true,
-			opts: []configOption{withQueueFactory(
-				func(_ queue.RegisteredQueueName, _ framework.ItemComparator) (framework.SafeQueue, error) {
+			opts: []configOption{
+				withIntraFlowDispatchPolicyFactory( // Forces queue instance creation for validating capabilities.
+					func(name intra.RegisteredPolicyName) (framework.IntraFlowDispatchPolicy, error) {
+						return &mocks.MockIntraFlowDispatchPolicy{
+							NameV:                      string(name),
+							RequiredQueueCapabilitiesV: []framework.QueueCapability{"required-capability"},
+						}, nil
+					},
+				),
+				withQueueFactory(func(_ queue.RegisteredQueueName, _ framework.ItemComparator) (framework.SafeQueue, error) {
 					return nil, errors.New("queue creation failed")
-				})},
+				}),
+			},
 		},
 		{
 			name: "ShouldError_WhenPolicyFactoryFails",

pkg/epp/flowcontrol/types/request.go

@@ -92,7 +92,8 @@ type QueueItemAccessor interface {
 	OriginalRequest() FlowControlRequest
 
 	// EnqueueTime is the timestamp when the item was logically accepted by the `controller.FlowController` for queuing
-	// (i.e., when `controller.FlowController.EnqueueAndWait()` was called).
+	// (i.e., when `controller.FlowController.EnqueueAndWait()` was called). It does not reflect the time the request
+	// landed in a `framework.SafeQueue` instance.
 	EnqueueTime() time.Time
 
 	// EffectiveTTL is the actual Time-To-Live assigned to this item by the `controller.FlowController`, taking into