perf(agents): remove quadratic scaling traversals for sessionprefixin…

[karen-sy]

Overview

This PR follows up on #13807 by improving SessionPrefixIndexer worker lifecycle handling, bounding session identifier storage, and reducing stored-chain validation overhead.

Details

Worker removal

• Clear session frontiers when a worker or DP rank is removed.
• Use worker-scoped residency generations to prevent stale route-time matches from restoring removed frontiers.
• Apply physical-index removal before flushing the corresponding session-index update.
• Preserve logical nodes shared by other workers or sessions.

Session identifier bound

Session IDs longer than 256 bytes are ignored before they create persistent SessionPrefixIndexer state.

Stored-chain validation

Definitions:

• k: blocks in one stored event.
• d: depth of the stored event's parent lineage.
• N: total lineage length across successive events.
• w: worker/rank entries with tracked session frontiers.
• b: frontier bindings for a removed worker.

Case	Previous behavior	New behavior
New logical suffix	O(k + d) time and temporary memory	O(k) time and memory
Existing chain with matching parents	O(k + d) per event and potentially O(N^2) across one-block replay	O(k) per event and O(N) across replay
Parentless leaf graft	O(k + d)	O(k)
Existing subtree graft	O(k + d) time and memory	O(k + d) time and O(k) memory
Whole-worker cleanup	Session frontiers could remain stale	O(w + b) frontier cleanup
Session-ID storage	Unbounded in identifier length	Bounded to 256 bytes per indexed identifier

The validator now avoids an ancestry walk for new blocks, existing edges with matching parents, and parentless leaf grafts. It walks parent pointers only when grafting an existing subtree. This avoids adding a persistent ancestor-query index.

Validation

• cargo fmt --all -- --check
• cargo test -p dynamo-kv-router session_prefix_index --lib
• cargo test -p dynamo-kv-router --features standalone-indexer services::indexer::backend::session_tests --lib
• cargo clippy -p dynamo-kv-router --all-targets --features standalone-indexer
• git diff --check

Results:

• 22 focused SessionPrefixIndexer tests passed.
• 7 backend session-update tests passed.
• Clippy passed with existing standalone-feature dead-code warnings.
• Formatting and diff checks passed.

Where should the reviewer start?

1. lib/kv-router/src/session_prefix_index.rs

   • Session-ID bound.
   • Optimized validate_chain().
   • Worker-wide frontier clearing.
   • Unit tests.

2. lib/kv-router/src/services/indexer/session_updates.rs

   • Worker-scoped residency generations.
   • WorkerRemoved session mutation.
   • Stale-match invalidation.

3. lib/kv-router/src/services/indexer/backend.rs

   • Physical-first worker and rank removal.
   • Session-update enqueue and flush integration.
   • Worker-removal regression test.

Related Issues

🔗 This PR is linked to an issue:

• Relates to DEP: Session-Aware Prefix Indexer #13279
• Follow-up to feat(router): add SessionPrefixIndexer for session-block lineage #13807
• DYN-4543

Summary by CodeRabbit

• Bug Fixes
  • Removing a worker or rank now clears its session frontiers, and rank resets clear the affected session state. Delayed updates no longer restore frontiers that were cleared during removal.
  • Session IDs longer than 256 bytes are rejected without changing the index.
  • Stored-chain validation now detects cycles and conflicting parents and reports these errors before unknown-parent errors.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: ai-dynamo/dynamo/.coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 9171ed1d-010c-4b0d-8345-f0044d465e33

📥 Commits

Reviewing files that changed from the base of the PR and between f673274 and 324c091.

📒 Files selected for processing (3)

• lib/kv-router/src/services/indexer/backend.rs
• lib/kv-router/src/services/indexer/session_updates.rs
• lib/kv-router/src/session_prefix_index.rs

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

---

Walkthrough

The indexer now clears session frontiers when workers or worker ranks are removed. Residency versions track both workers and worker ranks. Session-prefix updates reject IDs over 256 bytes, and stored-chain validation checks repeated hashes, cycles, and parent conflicts.

Changes

Worker frontier lifecycle

Layer / File(s)	Summary
Mutation and residency version model lib/kv-router/src/services/indexer/session_updates.rs	Residency versions now track worker IDs and worker ranks. WorkerRemoved has no rank-specific worker, so concurrent barrier flushing excludes it from rank-specific lanes.
Worker-wide frontier clearing lib/kv-router/src/session_prefix_index.rs	A worker-ID clearing operation removes frontiers across that worker’s ranks. The mutation advances the worker-wide version and invokes the clearing operation. Tests cover clearing all matching ranks while preserving other workers’ frontiers.
Removal mutation wiring lib/kv-router/src/services/indexer/backend.rs	Indexer removal paths enqueue and wait for session updates. Rank reset uses a shared helper. Removal errors are logged, and tests cover frontier cleanup and stale matches.

Session-prefix validation

Layer / File(s)	Summary
Session ID length limit lib/kv-router/src/session_prefix_index.rs	Both update methods return Ok(false) for IDs over 256 UTF-8 bytes before changing index state. Tests cover the limit and verify that oversized IDs add no nodes or sessions.
Stored-chain validation lib/kv-router/src/session_prefix_index.rs	Chain validation checks repeated hashes, cycles, conflicting parents, and unknown parents. An unknown parent remains acceptable when the chain reconnects a known parentless node.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to 324c0

No confirmed issue currently blocks merging. Worker removal and stored-chain validation preserve the examined behavior.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 43.75% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 32 functions across 3 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the main performance change: removing quadratic scaling traversals in SessionPrefixIndexer. It is concise and related to the primary objective.
Description check	✅ Passed	The description includes the required Overview, Details, reviewer guidance, Related Issues, and validation results. The Related Issues section identifies linked issues, although it does not use the te…

• Fix all pre-merge checks with AI

---

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

[dynamo-review-agent]

Previously reported defects still present:

• Original discussion: Stored session mutations remain unversioned and apply unconditionally, so an in-flight store can recreate a removed worker's frontier after worker or rank cleanup.
• Original discussion: The previously reported stale-store race remains present: Stored mutations carry no residency version and apply unconditionally, so a store queued before or during worker/rank removal can run after WorkerRemoved/Cleared and recreate a frontier for removed residency. The author explicitly deferred this lifecycle enforcement.
• Original discussion: The reported race remains present: Stored mutations carry no residency generation and are applied unconditionally. A store already enqueued to the primary can enqueue its session update after worker/rank cleanup, recreating a frontier for removed residency.