feat(precompute): dual-mode aggregation (per-series vs whole-stream) unified under Mode

[zzylol]

Summary

Adds dual-mode aggregation to the ASAP edge precompute runtime: every
sketch/aggregation family now supports both aggregation scopes, selectable
per-aggregation by the control plane.

• PerSeries (default / zero value): one sketch per series key (per
  AggregateBy group, honoring OmitResourceAttrs); each datapoint folds into
  its own series' sketch; one output envelope per series. Today's behavior —
  existing plans are byte-compatible.
• WholeStream: collapse grouping — a single sketch per AggID (per shard,
  merged at flush) ingests from every matching datapoint regardless of series
  identity; one output envelope per AggID per window. Resource attrs + dp labels
  are stripped from the series key and the emitted envelope.

Design

• New AggMode enum in asap-precompute-go/config.go (ModePerSeries=0 /
  ModeWholeStream) with String() + ParseAggMode. It serializes exactly like
  the package's other enums (plain integer, no custom MarshalJSON), so an
  omitted field decodes to the default.
• New field PrecomputeConfig.Scope AggMode. Naming note: the field is
  Scope, not Mode, because PrecomputeConfig.Mode is already taken by the
  existing AggregationMode (Tumbling/Sliding/Batch windowing strategy). Scope
  is orthogonal to the windowing mode; the enum constants stay Mode* so use
  sites read cfg.Scope == ModeWholeStream.
• WholeStream reuses the single series-map mechanism with a constant key per
  AggID rather than adding a parallel "single sketch slot" — so pooling
  (SketchSink), Reset, snapshot-cache, and delta encoding all work unchanged
  with zero new flush/rotate/drain code paths.

Merged / deprecated existing functionality

• GlobalAggregation bool is subsumed by Scope. A new effectiveScope()
  helper folds GlobalAggregation=true into ModeWholeStream, so the single
  WholeStream code path drives both. The bool is kept as a documented deprecated
  alias; the legacy emit_heap CountSketch path (which set GlobalAggregation)
  keeps working byte-for-byte. All four SeriesKey helpers + the window
  admit/strip path now branch on isWholeStream() instead of the raw bool, so
  the two signals can never disagree. A back-compat test asserts a
  GlobalAggregation config behaves identically to a Scope=WholeStream one.
• OmitResourceAttrs and the empty-AggregateBy path compose cleanly:
  WholeStream is the strict super-collapse (strips both resource + dp labels);
  the other flags only matter in PerSeries.
• Searched the whole tree for parallel "global/whole/scope/buildPartitionKey"
  mechanisms. The only one in these repos is GlobalAggregation (subsumed). The
  legacy standalone processors were already retired (Sum became first-class in
  Sum as first-class AggregationType (edge + vendored pdata) + google_cluster E2E harness #468); there is now ONE scope abstraction.

Per-family WholeStream semantics

Mode only changes routing; no sketchlib-go math changes. The ingested
subject is the metric value by default, or the inner item dimension when
ItemLabel is set (reconciled with the existing ItemLabel — no redundant
knob):

Family	value subject (default)	item subject (ItemLabel set)
Sum	grand total	n/a
DDSketch / KLL	pooled value distribution	n/a
HLL	distinct values	distinct items
CountMinSketch	value frequency	per-item frequency
CountSketch (+heap)	value frequency / heavy values	heavy items (top-k)

UpdateConfig

A live scope flip cannot hot-swap in place (the series map is keyed
incompatibly across scopes), so UpdateConfig resets the in-flight window on a
scope transition; same-scope changes stay in place (preserving accumulated
window bytes, per the documented contract).

asap_edge wiring

MetricFamily gains a mode mapstructure field (per_series default /
whole_stream), validated at config boot and plumbed to
PrecomputeConfig.Scope. MaxSeries is a no-op under WholeStream.

Controller follow-up (not in these repos)

The scope is "decided by the control plane given the queries." The wire field
(PrecomputeConfig.Scope) and the operator-facing knob (MetricFamily.Mode)
now exist and are documented. The query→PrecomputeConfig mapping lives in the
controller's deployment-model layer (/mydata/ASAPController emits L3
AggIntent), which is NOT present in these repos, so no controller code was
fabricated. The controller must set Scope/mode per aggregation:
distinct-count / global-quantile / grand-total / global-top-k queries →
whole_stream; per-label-group queries → per_series.

Tests

• asap-precompute-go/scope_test.go: AggMode String/parse, JSON round-trip
  (with + without the field), effectiveScope folding, PerSeries→N vs
  WholeStream→1 with pooled semantics, GlobalAggregation back-compat parity,
  MaxSeries no-op, scope-change window reset (and same-scope preservation).
• asapedgeprocessor/whole_stream_test.go: Sum grand-total, DDSketch pooled
  quantile, HLL distinct (item dimension projected + grouping collapsed),
  per-series-vs-whole-stream fan-out, and mode validation.
• go test ./..., go vet ./..., gofmt -l all pass for both the
  asap-precompute-go module and the asapedgeprocessor module.

Build note: the asapedgeprocessor source of truth is
opentelemetry-collector-contrib-patch/processor/asapedgeprocessor/ (committed
in this private repo); restore_otel_collector_contrib_patches.sh stages it
onto the upstream-pinned contrib submodule for the build/test.

🤖 Generated with Claude Code