feat(engine): GorillaQueryEngine — exact PromQL over Gorilla-S3 chunks (Phase 4)

[zzylol]

Summary

Phase 4 of the Gorilla-S3-cold-engine: a sibling of SimpleEngine that
executes PromQL exactly against the Phase-3 GorillaS3ColdStore
(merged in PR #84). Same PromQL surface, different backend — instead of
warm-tier sketches with ε/δ bounds, this engine reads decoded
GORILLA1 chunks straight off S3 and folds them into the answer with
AccuracyEnvelope { kind: Exact, ε: 0, δ: 0 }.

Architecture

asap-query-engine/src/engines/gorilla_engine/ (new directory, 4 files):

• mod.rs — GorillaQueryEngine (holds Arc<dyn ColdStore> so
  tests can inject mocks; production constructor with_gorilla_s3
  keeps the design.md type signature). Public surface: execute(query)

  • execute_at(query, now_ms). wrap_result attaches the exact
    accuracy envelope + the request window. GorillaEngineConfig with
    max_buffered_samples (default 10M) + query_timeout_secs (default
    30s). EngineError::{Plan, ColdStore, TooManySamples, Timeout}.
    ExecutionOutcome carries (value, samples_scanned, chunks_fetched)
  • info_lines() builder pinning the on-wire info strings.

• query_planner.rs — minimal PromQL → QueryPlan translator.
  Supports sum/count/avg/min/max_over_time, rate, increase,
  quantile_over_time(φ, m[range]), and topk(k, <vector>) (PromQL
  grammar requires the inner be a vector so topk(k, sum_over_time(m[range])) is the legal spelling).

• exact_executor.rs — ExactExecutor dispatches per
  QueryStatistic:

  • Streaming-additive (Sum / Count / Avg / Min / Max / Rate /
    Increase): walks chunks one at a time, folds into a bounded
    AdditiveAccumulator, drops the decoded chunk before
    fetching the next. Memory cost is O(1) per query.
  • Buffered (Quantile / TopK): materialises every in-range
    sample up to max_buffered_samples; over-budget queries fail
    fast with EngineError::TooManySamples rather than OOM.

• tests.rs — 20 unit tests via an in-process MockColdStore.

Result wrapping

Every result carries:

• AccuracyEnvelope::single(AccuracyProfile::exact()) (ε = 0, δ = 0,
  kind = Exact),
• data_source: gorilla_archive info marker,
• samples_scanned / chunks_fetched diagnostics.

The data_source: gorilla_archive line is exposed via
ExecutionOutcome::info_lines() so the HTTP driver layer can surface
it on the Prometheus infos array (matching the existing
SimpleEngine convention).

Test plan

• cargo build --release -p query_engine_rust clean
• cargo test --release -p query_engine_rust gorilla_engine —
  20 / 20 pass
• cargo clippy --release -p query_engine_rust --all-targets — 0
  warnings on the new module (5 pre-existing warnings in unrelated
  files; not touched per scope guard)
• All 15 spec'd test names present:
  • execute_sum_over_time_streaming,
    execute_count_over_time, execute_avg_over_time,
    execute_min_over_time, execute_max_over_time,
    execute_rate_basic, execute_increase_basic,
    execute_quantile_buffered_basic,
    execute_quantile_too_many_samples_errors,
    execute_topk_basic,
    execute_empty_chunks_returns_zero_or_nan,
    execute_chunks_partially_outside_range_filtered,
    result_carries_exact_accuracy_envelope,
    result_includes_data_source_gorilla_archive,
    engine_respects_config_timeout
• Touches only the new engines/gorilla_engine/ dir + the engines
  mod.rs re-export (no simple_engine.rs, no cold-store, no
  sketch warm-tier).
• Zero docker. Zero new Cargo deps.

Open question for Phase 5

GorillaQueryEngine and SimpleEngine are now sibling engines with
disjoint surface — Phase 5's capability router needs a hook to choose
between them per query. The engine exposes config() for the cost
estimator; a follow-up trait abstraction (pub trait QueryEngine)
would let the router hold an Arc<dyn QueryEngine> and dispatch
without case-on-concrete. Deferred to Phase 5 per scope guard.

Doc tightening for design.md §6

The data_source marker in §6.6 of design-gorilla-s3-cold-engine.md
reads gorilla-s3; this PR ships gorilla_archive per the Phase 4
spec (snake_case + the "archive" tier name preferred by the controller
side). The doc lives in the ASAPCollector repo and is out of scope
for this PR — a follow-up doc PR should align the string.

🤖 Generated with Claude Code