Ranking & Tie-Breaking

Reciprocal Rank Fusion (RRF)

Because ContextOS merges signals from distinct algorithms (FTS5 BM25 vs BFS Graph Expansion), their raw scores cannot be directly compared. FTS5 produces unbounded negative floats, while BFS produces exponential decay vectors.

We normalize these signals using Reciprocal Rank Fusion:

const K = 60;
function rrfScore(rank: number): number {
  return 1 / (K + rank);
}

The Determinism Problem

Standard sorting in V8 is unstable if scores are identical. If a query produces identical scores for two files across multiple executions, the sort order could flip unpredictably. This creates non-deterministic context windows, confusing the LLM across multi-turn chats.

ContextOS enforces strict determinism via a stable tie-breaker:

results.sort((a, b) => {
  if (Math.abs(a.score - b.score) > 1e-9) {
    return b.score - a.score;
  }
  // Deterministic tie-breaker
  return a.id.localeCompare(b.id);
});

Heuristic Boosts

Scores are aggressively modified by deterministic heuristics:

• Layer Promotion: Workspace-local entities are multiplied by 10.0x to override Global cache conflicts.
• Intent Detection: If the query specifies an intent (e.g. "definition" vs "usage"), exact AST type matches (e.g., interface) receive a 1.5x boost.
• File Extensions: Binary and unreadable files are hard-capped at score = 0.