Support universal Top-K query engine

[em3s]

Background

Add a universal Top-K query engine to support precomputed ranking queries (e.g., trending lists, leaderboards, user preferences) as first-class operations.

Conceptually, topk acts as a ranking operator over Actionbase's aggregation engine (agg):

topk(agg(...))

Consequently, all aggregation logic (e.g., counts, sums, weighted multi-edge merging, time-decay) must reside within the agg layer. The topk engine is strictly responsible for performing flat O(K) ranking queries over these pre-aggregated states, ensuring a clean decoupling of write-time aggregation and read-time ranking.

Interface

topk(Target | [Filter], [Window])

The engine will support 4 query shapes:

Shape	Signature	Example
1	topk(Target)	Most active users (All time)
2	topk(Target | Window)	Trending items this week
3	topk(Target | Filter)	Most purchased items by a user
4	topk(Target | Filter, Window)	Recent category heavy users / User's recent purchases

Done When

• Universal topk interface is supported, and "top purchased items per user within the last year (Shape 4)" works as the initial target.
• Read latency remains bounded at O(K), independent of total interaction volume.
• Comprehensive unit/integration tests and documentation are completed.

Notes

• Decoupled Writes: Index updates for ranking must not block or bottleneck the primary write/mutation path.
• Pre-aggregated State: Top-K lists are maintained via bucket pre-aggregation to avoid full-scan lookups.
• Signature Degradation: Since Shape 4 is the superset query signature, implementing it with optional Filter and Window parameters naturally satisfies Shapes 1, 2, and 3 as omitted parameter fallbacks.