P0.6 — elasticsql: cap-hit funnel instrumentation

[fupelaqu]

Story P0.6 — Pricing-funnel instrumentation (cap-hits), elasticsql leg

Closes #129. Cross-repo P0.6 epic leg 1 of 4 (elasticsql → softclient4es-extensions → softclient4es-arrow → softclient4es-license-server). Phase 0 final story.

Cap-hits (count of license quota rejections by quota type) are the launch leading indicator — PRD §15.1 / pre-mortem Killer #2 — and the only missing funnel signal class (Epic 15 already ships conversion/activation/chasm). This leg adds the SEMANTIC cap-hit primitive to the shared TelemetryCollector and wires the maxQueryResults reject site.

Changes

• licensing/.../TelemetryCollector.scala: new CapHitKind sealed trait {MaterializedViews, QueryResults, Joins, Clusters} (each with a snake-case wire key); four independent lock-free AtomicLong cap-hit DELTA buckets; incrementCapHit(kind); collectAndResetCapHits() (getAndSet, always all four keys); TelemetryData.capHitsByKind populated in collect (read, no reset — like joinQueryCount) and collectAndReset (getAndSet flush); Noop overrides. Mirrors the Story-15.3 JOIN-bucket pattern exactly.
• core/.../extensions/CoreDqlExtension.scala: capture capHitCollector = licenseRefreshStrategy.telemetryCollector at initialize; incrementCapHit(QueryResults) on both capOrReject branches — the explicit-LIMIT 402 reject AND the P0.5 no-LIMIT truncation/cappedScroll bite (OQ-2). Suppressed JOIN legs (ResultCapContext.isSuppressed) do not count → no double-count. The reject itself is unchanged (AC8: increment is a side-effect before the existing return). The closed EnforcedDqlExtension inherits the increment via the shared capOrReject.
• Tests: TelemetryCollectorSpec (+10 cap-hit cases: per-kind isolation, all-4-keys, collect-no-reset, collectAndReset delta, concurrency, Noop no-op), CoreDqlExtensionSpec (+5: 402 branch + truncation branch increment, no-increment for within-quota/suppressed-leg/Enterprise).

Design decisions

• OQ-1 — instrument by SEMANTIC quota-rejection (incrementCapHit(kind) at each reject site), NOT by 'HTTP status == 402' (only MV + maxQueryResults raise a 402; joins return Left(String), clusters a LicenseError/sys.exit).
• OQ-2 — the P0.5 no-LIMIT truncation IS counted as a QueryResults cap-hit (the meter biting non-fatally).
• Cap-hits ride the existing InstancePing daily-ping delta (read via collect, like joinQueryCount); the license-server computes per-instance deltas from the stored previous snapshot.

Build & verify

• + core/compile + + licensing/compile + + softclient4es-core-testkit/compile (cross 2.12 + 2.13) — green
• licensing/testOnly *TelemetryCollectorSpec — 24 passed; core/testOnly *CoreDqlExtensionSpec — 14 passed; headerCheck — clean
• publishLocal'd softclient4es-core + softclient4es-licensing 0.20-SNAPSHOT (2.12+2.13) — unblocks the extensions + arrow legs

Sibling PRs

• softclient4es-extensions (MV cap-hit + thread cap-hits into InstancePing): to follow
• softclient4es-arrow (Joins + Clusters cap-hits + shutdown flush): to follow
• softclient4es-license-server (proto fields 14-17 + instance_ping migration + Grafana panel): to follow

🤖 Generated with Claude Code