[DO-NOT-MERGE-YET] complexity cache-aware session routing integration

[Madhuvod]

Summary

Cache-aware session mode previously shared a single code path with pinned mode, which meant it could not correctly handle per-turn classification, atomic tier-change decisions, or the distinction between a held tier and a freshly classified one. This PR splits the two modes into separate implementations so each behaves correctly and independently.

Changes

• Extracted classifyWithPinnedSession and classifyWithCacheAwareSession from the single withComplexitySession closure, replacing a mode-conditional branch inside one function with two dedicated paths dispatched by a switch on state.Config.Mode.
• Cache-aware mode now classifies on every relevant turn, then calls store.Update atomically to decide whether the session may move. An unchanged decision aborts the replicated write and falls back to a coarse Get to slide the TTL, avoiding one write per request when the tier is stable.
• Pinned mode retains its original behaviour: look up the stored tier, return it if found, classify and persist only on the first turn.
• Replaced the two separate Mode and TTL fields on complexitySessionState with a single Config configstore.ComplexitySessionConfig snapshot, so both paths read from the same policy values captured at request start and cannot mix thresholds from a concurrent config reload.
• Added publishCacheAwareSessionTier to log the policy decision (tier, proposed tier, switched flag, reason, identity) and clear the score from context when the held tier differs from the proposal, preventing a score calculated for one tier from being attributed to another.
• Added persistInitialSessionTier as a shared helper used by both modes when writing the first record for a new session.
• Added errSessionTierDecisionUnchanged sentinel so Update can abort without a replicated write while still allowing the caller to distinguish a no-op from a real error.
• Added failingUpdateSessionStore test double and five new test cases covering: no replicated write on an unchanged cache-aware tier, escalation with semantic mechanism preserved, sustained-downgrade gating, hold when classification produces no tier, and fallback to the proposal when Update fails.
• Updated schema descriptions, UI copy, and comments throughout to accurately describe what each mode does, particularly that cache-aware mode pays an embedding cost on every complexity-routed turn.

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

# Core/Transports
go test ./plugins/governance/... -run TestWithComplexitySession
go test ./plugins/governance/... -run TestRecordSessionRouteObservation
go test ./...

# UI
cd ui
pnpm i || npm i
pnpm build || npm run build

Validate cache-aware behaviour end-to-end by configuring a session with mode: cache_aware, sending several turns with the same session identity, and confirming via routing engine logs that:

• Every complexity-routed turn shows a Cache-aware complexity session log entry with switched=false when the tier is stable.
• No replicated store write occurs on unchanged decisions (observable via store metrics or delegate counters in tests).
• A turn whose classifier proposes a higher tier and meets the confidence threshold shows switched=true and the new tier takes effect immediately.
• A downgrade proposal accumulates pending_turns until downgrade_after_n_turns is satisfied before switching.

Breaking changes

• Yes
• No

Related issues

Security considerations

No auth, secrets, PII, or sandboxing changes. Session keys remain tenant-namespaced and TTL-bounded as before.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: f6ae78ed-e2c0-437d-a551-bc6a9697c3c8

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[Madhuvod]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• [DO-NOT-MERGE-YET] add llm classifier fallback #6074
• [DO-NOT-MERGE-YET] fix: use correct "latest" route when fallbacks are configured #6061
• [DO-NOT-MERGE-YET] feat(complexity): add session routing observability #6045
• [DO-NOT-MERGE-YET] complexity cache-aware session routing integration #6043 👈 (View in Graphite)
• [DO-NOT-MERGE-YET] complexity cache-aware session tier policy #6042
• [DO-NOT-MERGE-YET] complexity session route observations #6029
• [DO-NOT-MERGE-YET] complexity session routing and store readiness #6028
• [DO-NOT-MERGE-YET] sessions ui #6018
• [DO-NOT-MERGE-YET] feat(complexity): add session state foundation and identity resolution #6015
• [DO-NOT-MERGE-YET] feat(complexity): add session state contract and identity resolution #6009
• [DO-NOT-MERGE-YET] session routing config and sticky targets #5901
• semantic router: incremental embedding + embed usage accounting #5896 : 1 other dependent PR (#5924 )
• semantic router ui revamp #5865
• move complexity exemplars to configstore with backfill migration #5842
• feat(complexity): harness-aware complexity input extraction for cc and codex #5810
• server: export ObserveWarmupRoutingEmbedding for enterprise #5791
• weaviate + redis adapter fixes #5790
• semantic routing ui #5743
• semantic router: dimension probe + message history window #5748
• semantic cache: min similarity + fallback logging #5742
• smenatic router: budgeting+telemetry management #5686
• semantic routing #5: added semantic classifier for complexity router + handlers changes #5680
• semantic router #3: embedding executor #5656
• semantic router #2: semantic routing config #5655
• semantic router #1: add chromem backend #5628
• complexity : reducing keyword lists from 4 -> 3 lists #5602
• helm and docs changes #5530
• update complexity boundaries #5529
• expose tier/mechanism on every surface #5499
• structured logging #5497
• complexity tier merge #5494
• dev

This stack of pull requests is managed by Graphite. Learn more about stacking.