fix(router): session affinity runs in every shipped routing mode

[andrei-hasna]

Defect

Session affinity (sticky_session_id / session_id) never ran in any shipped routing mode — todos 7dd67da6-9ede-483a-ac3f-acd21cecd7f5, measured at main 21fc5db during PLA23-00044. Mechanism, confirmed by driving resolveRoute directly in all seven modes with a session id varied across a two-candidate config:

• cheapest, fallback, explicit: sortCandidates returned before stickyTieBreaker was ever computed — the code path was literally unreachable.
• Scored modes (lowest-latency, highest-throughput, balanced, smart): sticky was consulted only after EXACT float score equality. Minmax normalization maps any two distinct metric values to 0 and 1, so even near-identical candidates (500ms vs 505ms latency) score far apart — the tie-break fired only for byte-identical candidate stats, never in a realistic config.

Probe evidence (pre-fix): with any differing stats, 16 distinct session ids produced one identical winner in all seven modes; the session id was routing-inert.

Fix

A stateless affinity pass (applySessionAffinity) runs in EVERY mode after the mode's own ordering. Groups of candidates the mode does not distinguish — equal configured price in cheapest, candidates a provider_order hint leaves unranked (shared Infinity rank) in fallback/explicit, weighted scores within SESSION_AFFINITY_SCORE_EPSILON (0.01 on the 0..1 scale) in scored modes — are ordered by the existing deterministic per-session FNV-1a hash.

Boundaries, stated so nobody over-reads it:

• A candidate the mode ranks strictly better is NEVER overridden by affinity.
• Without a session id, ordering is byte-identical to previous behavior.
• Ranked provider_order candidates and configured fallback chains are never shuffled.
• Affinity across requests holds by construction (same session → same hash → same candidate while the eligible set is stable). A persisted session→provider store remains out of scope and is not claimed — the row's "decide before fixing" question is answered as: affinity IS wanted (the platform core/gateway module's contract names it), delivered stateless.

Every decision now discloses the path: decision.session_affinity = { session_id_present, applied } — additive optional field, which is what makes the path observable and red/green testable per mode. When affinity ordered a group, decision.reason gains "; session affinity ordered materially-equal candidates".

Tests (written first, red on pre-fix tree)

tests/router-affinity.test.ts, 17 tests: at 21fc5db + test file only — 0 pass / 17 fail. Post-fix — 17 pass / 0 fail / 186 expect() calls. Coverage: all seven shipped modes (affinity path executes AND the session id decides a tie, deterministically, with a probe-derived disagreeing session pair), same-session stability across repeats, the no-session control (unchanged selection, disclosed applied: false), pooled-identical-model shape with a clearly worse third candidate never joining the tie group, clear winners never sacrificed, ranked provider_order never shuffled.

Full suite bun test: 259 pass / 0 fail. bun run typecheck and bun run build clean.

Closes todos row 7dd67da6-9ede-483a-ac3f-acd21cecd7f5. Part of platform wave-2 package capacity-cli-and-affinity.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[andrei-hasna]

[REVIEW] NO_GO — #24 @ d015cac — lens: correctness+security+gates, reviewer unresolved-account001 (1 of 1)

Reviewed the full diff against fetched base 21fc5dbe28bc0066cc90d2b9306c3589a84b3a96 for docs/routing-and-policy.md, src/router.ts, src/types.ts, and tests/router-affinity.test.ts, plus the surrounding candidate-resolution and runtime fallback paths in src/router.ts, src/gateway.ts, request/config types, config validation, and existing router tests.

Commands and gates:

• git log --oneline origin/main..HEAD — exit 0; one commit, d015cac.
• git diff origin/main...HEAD --stat and each complete changed-file diff — exit 0.
• bun install — exit 0; setup only, not reported as a test gate.
• bun run typecheck — exit 0; PASS, no per-test counts emitted.
• bun run test — exit 0; PASS: 258 pass, 1 skip, 0 fail, 925 assertions across 259 tests.
• Focused same-provider fallback probe through resolveRoute — exit 0; 32 session ids selected both p/first and p/second even though fallbackModelIds ordered p/first first and provider_order explicitly ranked their shared provider.

Blocking findings:

1. P1 correctness — ranked candidates from the same provider are shuffled, violating the configured fallback chain. src/router.ts:665-672 assigns every model from a ranked provider the same numeric provider rank, then passes that rank to applySessionAffinity. Two ordered fallback models from one ranked provider therefore form an affinity group and are reordered by session hash. This is a supported path: GatewayRoutePolicy.fallbackModelIds is ordered, initialCandidates preserves that order (src/router.ts:243-249), and the runtime consumes the returned candidate order as its retry/fallback order. The PR body and docs state that ranked provider_order candidates and configured fallback chains are never shuffled, but the probe returned winners p/second and p/first across sessions. A request can therefore use the configured secondary before the primary.

Required focused remedy: preserve original order for every candidate whose provider appears in provider_order; apply affinity only to the unranked Infinity group. Add a regression with two ordered models on the same ranked provider and prove every session keeps the first model first. Re-run the affected typecheck and test lanes.

Security findings: none. The session id changes ordering only inside the already policy-filtered eligible set; no new credential, authorization, tenant, or data-exposure path was found.

Non-blocking follow-ups: none.

[andrei-hasna]

[REVIEW] GO — #24 @ 87eb350 — lens: correctness+security+gates, reviewer unresolved-account001 (1 of 1)

Focused re-review of the one named P1 from the prior d015cac5f99e4b74feb35cc71248f69f5aaf94ea NO_GO and its direct regressions.

Fix verified:

• Ranked candidates now receive distinct affinity keys based on their original positions; only candidates whose providers remain unranked share the Infinity affinity key.
• Added a regression covering both fallback and explicit with two ordered models on one ranked provider across 64 session ids per mode.
• The regression was red before the fix: bun run test exit 1, 258 pass / 1 skip / 1 fail.
• bun run typecheck after the fix — exit 0, PASS.
• bun run test after the fix — exit 0, PASS: 259 pass / 1 skip / 0 fail, 1309 assertions across 260 tests.
• The original direct resolveRoute probe after the fix — exit 0: only p/first selected across 32 session ids and session_affinity reported { session_id_present: true, applied: false }.
• shield review on the staged fix — exit 0: No security issues found in staged changes.
• Commit provenance verified: 87eb3507e38e59cf1d57f659d34b77c11b806046, final trailer Agent: unresolved-account001.

Blocking P0/P1 findings: none. The prior P1 is fixed and its affected lanes pass.

Non-blocking follow-ups: none.