docs: document request attempt budget helpers

Author: ndycode

lib/request/request-attempt-budget.ts

@@ -2,13 +2,21 @@ const MAX_TOTAL_OUTBOUND_REQUEST_ATTEMPTS = 6;
 const MAX_STREAM_FAILOVERS = 1;
 const MAX_STREAM_FAILOVER_CANDIDATES = 2;
 
+/**
+ * Clamp configured stream failover retries to the conservative runtime cap.
+ */
 export function capStreamFailoverMax(value: number): number {
 	return Math.max(
 		0,
 		Math.min(MAX_STREAM_FAILOVERS, Math.floor(Number.isFinite(value) ? value : 0)),
 	);
 }
 
+/**
+ * Compute a finite per-request budget that bounds all outbound Responses API
+ * fetches across account rotation, same-account retries, empty-response
+ * retries, and stream failover.
+ */
 export function computeOutboundRequestAttemptBudget(params: {
 	accountCount: number;
 	maxSameAccountRetries: number;
@@ -49,6 +57,13 @@ export function computeOutboundRequestAttemptBudget(params: {
 	);
 }
 
+/**
+ * Build the ordered stream-failover candidate list for a request.
+ *
+ * The caller is expected to pass a valid primary account index from the
+ * current account snapshot. This helper keeps the primary first and adds at
+ * most one alternate account to avoid broad replay fan-out.
+ */
 export function buildStreamFailoverCandidateOrder(
 	primaryIndex: number,
 	accountIndices: number[],