docs(core): keep L3 TopK intent sketch-agnostic

AggIntent::TopK { k, accuracy } is a pure L3 intent (k most frequent by
value, to accuracy ε), built from the lowering accuracy context exactly
like Quantile/Cardinality. Its doc claimed it "is served by a dedicated
sketch (SpaceSaving, CMS-with-heap) in one pass" and "never materialises-
then-sorts" — physical-strategy language that belongs to L4 and is false
for accuracy: Exact. Reframe the docs as intent-only and defer the
exact-vs-sketch realisation to L4, matching the module's own rule that the
HashAgg/SortAgg/SketchAgg choice is an L4 cost-aware decision. Keep the
legitimate lowering-time split (heavy-hitter intent vs generic Sort+Limit).

Doc/comment-only; no behavior change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: zzylol

crates/core/src/intent_algebra/agg_intent.rs

@@ -4,10 +4,14 @@
 //! between `HashAgg` / `SortAgg` / `SketchAgg(KLL{k=200})` is an L4 cost-aware
 //! decision, not encoded here.
 //!
-//! `AggIntent::TopK` is a first-class *intent* — a dedicated heavy-hitter
-//! sketch (SpaceSaving, CMS-with-heap) computes it in one pass. Generic
-//! `ORDER BY value LIMIT k` stays as the `QueryExpr::Sort + Limit` operator
-//! pair. L1→L2→L3 lowering picks one or the other deterministically.
+//! `AggIntent::TopK` is a first-class *intent*: "the k most frequent keys by
+//! value, to accuracy ε." Like `Quantile`, the exact-vs-approximate
+//! realisation — an exact heap / sort+limit when `accuracy: Exact`, a
+//! heavy-hitter sketch when approximate — is an L4 cost-aware decision, not
+//! encoded here. The semantic distinction that *is* made at lowering is
+//! intent vs operator: a heavy-hitter aggregate becomes `TopK`, whereas a
+//! generic `ORDER BY value LIMIT k` stays as the `QueryExpr::Sort + Limit`
+//! operator pair.
 
 use serde::{Deserialize, Serialize};
 
@@ -66,8 +70,8 @@ pub enum AggIntent {
         q: f64,
         accuracy: AccuracyTarget,
     },
-    /// Heavy-hitter top-k — served by a dedicated sketch in one pass. The
-    /// group-by keys live on the enclosing `Aggregate.by`.
+    /// Heavy-hitter top-k to the given accuracy. The group-by keys live on
+    /// the enclosing `Aggregate.by`.
     TopK {
         k: usize,
         accuracy: AccuracyTarget,

crates/lower/src/promql.rs

@@ -24,7 +24,7 @@
 //! | `changes` / `resets` / `group` / `offset` / `@` | **rejected** — distinct semantics with no intent-algebra representation yet |
 //! | `OUTER by (dims) (…)` | `Aggregate.keys = dims` (→ positional `Aggregate.by` in L3; generic `topk by`/`bottomk` grouping → `Sort.partition_by`) |
 //! | `count by (d) (…)` | `Aggregate{[CountDistinct], …}` (→ `Cardinality`) |
-//! | `topk(k, count_over_time(…))` | `TopK{k, by}` (heavy-hitter, one pass) |
+//! | `topk(k, count_over_time(…))` | `TopK{k, by}` (heavy-hitter intent) |
 //! | `topk(k, <other>)` / `bottomk(k, …)` | `Sort{value} → Limit{k}` |
 //! | `m{f}` | `Filter(Source)` |
 //! | `a OP b` | `BinaryOp{vector_match}` |
@@ -400,10 +400,10 @@ fn build(inner: Inner, keys: Vec<ColumnRef>, outer: Outer) -> Result<L2> {
             }
         }),
         Outer::TopK { k, descending } => {
-            // Heavy-hitter only when ranking by frequency (`count`): a dedicated
-            // sketch serves it in one pass → first-class `TopK`. Any other
-            // ranking (topk over avg/quantile, all bottomk) is generic
-            // order-by-value + limit.
+            // Heavy-hitter only when ranking by frequency (`count`): that is a
+            // first-class aggregate intent → `TopK`. Any other ranking (topk
+            // over avg/quantile, all bottomk) is a generic order-by-value +
+            // limit and stays as the `Sort + Limit` operator pair.
             let heavy_hitter = descending && matches!(inner.func, Some(InnerFunc::Count));
             if heavy_hitter {
                 // Preserve the Count intent in L3 so the intent algebra is

crates/lower/tests/promql_conformance.rs

@@ -561,7 +561,7 @@ fn set_ops_lower_to_binaryop() {
 
 #[test]
 fn topk_over_count_is_heavy_hitter() {
-    // SEMANTICS: top-k by frequency → single-pass heavy-hitter sketch.
+    // SEMANTICS: top-k by frequency → first-class heavy-hitter `TopK` intent.
     let qe = ok("topk(10, count_over_time(http_requests_total[1m]))");
     assert!(has(
         &qe,