Summary
GetSymbolHotspots (DbSymbolReader.cs:~1376-1625) ranks results by reference_count DESC as the primary key, but the secondary order is whatever SQLite's row visit happens to be — typically rowid order, which can change after a VACUUM, schema migration, or even a different query plan choice. The MCP tool definition documents the primary sort but says nothing about tie-breaking, and the result set's order is not stable run-to-run when ties exist. AI clients and tools that diff hotspots output across runs see spurious churn.
Where
Suggested approach
(1) Add a documented secondary sort: ORDER BY reference_count DESC, path ASC, line ASC, name ASC (or whatever tuple guarantees uniqueness). (2) Emit the resolved sort_key tuple in the response shape so a client can verify the order matches expectations. (3) Document in the tool description: "ties broken by (path, line, name) for determinism across runs." (4) Add a regression test that runs hotspots twice — once before VACUUM, once after — and asserts the order is byte-identical. (5) Optionally add sortBy parameter to allow users to flip to ascending count or sort by path. (6) Cross-link with #1534, #1808, C555 (stability contract).
Summary
GetSymbolHotspots(DbSymbolReader.cs:~1376-1625) ranks results byreference_count DESCas the primary key, but the secondary order is whatever SQLite's row visit happens to be — typically rowid order, which can change after aVACUUM, schema migration, or even a different query plan choice. The MCP tool definition documents the primary sort but says nothing about tie-breaking, and the result set's order is not stable run-to-run when ties exist. AI clients and tools that diff hotspots output across runs see spurious churn.Where
src/CodeIndex/Database/DbSymbolReader.cs:~1376-1625(GetSymbolHotspots)src/CodeIndex/Mcp/McpToolDefinitions.cs(hotspots tool schema — no tie-break clause)Suggested approach
(1) Add a documented secondary sort:
ORDER BY reference_count DESC, path ASC, line ASC, name ASC(or whatever tuple guarantees uniqueness). (2) Emit the resolvedsort_keytuple in the response shape so a client can verify the order matches expectations. (3) Document in the tool description: "ties broken by (path, line, name) for determinism across runs." (4) Add a regression test that runshotspotstwice — once beforeVACUUM, once after — and asserts the order is byte-identical. (5) Optionally addsortByparameter to allow users to flip to ascending count or sort by path. (6) Cross-link with #1534, #1808, C555 (stability contract).