docs(planner): keep top-k in the optimizer example workload

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: milindsrivastava1997

.design_docs/optimizer-label-set-facts.example.yaml

@@ -3,7 +3,9 @@ series:
   - {metric: http_requests_total, spatial_filter: 'env="prod"', series_count: 200}
   - {metric: latency_ms, spatial_filter: "", series_count: 50}
 groups:
-  # sum by (job): output labels [job].
+  # sum by (job): output labels [job]; also the `topk by (job)` buckets.
   - {metric: http_requests_total, spatial_filter: 'env="prod"', grouping_labels: [job], cardinality: 10}
+  # topk keeps every label: output labels are all of them.
+  - {metric: http_requests_total, spatial_filter: 'env="prod"', grouping_labels: [env, instance, job], cardinality: 200}
   # quantile_over_time keeps every label.
   - {metric: latency_ms, spatial_filter: "", grouping_labels: [instance], cardinality: 50}

.design_docs/optimizer-v1-implementation-plan.md

@@ -353,7 +353,8 @@ Takes the same `ControllerConfig` YAML format as `asap-planner --input_config`;
 `metrics:` hints are required and must cover every workload metric, since they supply the
 label schema. `--label-set-facts` is a YAML file of externally provided facts — the optimizer
 never estimates them (example: `optimizer-label-set-facts.example.yaml`, for the workload
-`optimizer-workload.example.yaml`):
+`optimizer-workload.example.yaml`; its top-k query needs `--atomic-costs` with a CMS-with-heap
+reference row, otherwise the run fails with that item listed as unservable):
 
 ```yaml
 series:                         # per (metric, spatial_filter)
@@ -378,7 +379,8 @@ containing the exact `profiles[].workload` value from that benchmark artifact.
 The loader validates the document schema and rejects a selector that matches
 zero or multiple profiles; it never mixes entries across workloads. Omit both
 flags and ordinary unbenchmarked candidates use the flat stub, while
-CMS-with-heap candidates warn and are dropped until a matching reference row is available.
+CMS-with-heap candidates warn and are dropped until a matching reference row is available;
+an item left with no candidate makes the run fail, listing every unservable item.
 
 ### Running with real sketch-bench costs
 

.design_docs/optimizer-workload.example.yaml

@@ -1,8 +1,11 @@
 # Example workload for asap-optimizer-cli; facts in optimizer-label-set-facts.example.yaml.
+# The top-k query is only servable with --atomic-costs containing a CMS-with-heap
+# reference row; without it the optimizer reports it as unservable.
 query_groups:
   - queries:
       - 'sum by (job) (http_requests_total{env="prod"})'
       - 'quantile_over_time(0.99, latency_ms[5m])'
+      - 'topk by (job) (5, sum_over_time(http_requests_total{env="prod"}[5m]))'
     repetition_delay_ms: 60000
 metrics:
   - {metric: http_requests_total, labels: [job, instance, env]}