Module analytics Roadmap

Analytics Module Roadmap

Current Status

Production analytics runtime exists across OLAP, streaming/CEP, forecasting, anomaly detection, model-serving integration, and distributed analytics coordination. Gap closure Phase 2 (Core Implementation) complete with 40/40 functions delivered (2026-08-15).

Gap Closure Work (2026-08-15) - Phase 2

Overview

Phase 2 (Core Implementation) delivered 40 production implementations closing all identified gaps in the analytics module across 5 batches:

Batch 2A: Process Mining Core - [x] Complete

• createDFG() - Build directly-follows graph
• discoverProcess() - Process discovery orchestration
• analyzeVariants() - Trace variant analysis
• clusterVariants() - K-means variant clustering
• checkConformance() - Token replay conformance checking
• Helper functions - Topological sort, SCC detection, reachability

Batch 2B: AutoML & Forecasting - [x] Complete

• selectMetalearner() - Algorithm selection from feature space
• selectEnsembleMethod() - Ensemble strategy selection
• validateTrainingData() - Feature matrix validation
• validateTestData() - Test set validation
• seasonalityDuration() - Autocorrelation-based period detection
• exponentialSmoothing() - Holt-Winters triple exponential smoothing

Batch 2C: Streaming & CEP - [x] Complete

• buildNFA() - NFA construction from pattern string
• processWindows() - Window state machine transitions
• updateWindow() - Tumbling/sliding window semantics
• flushWindow() - Aggregation result publication
• updateAggregation() - O(1) incremental aggregation

Batch 2D: Knowledge Base - [x] Complete

• assertFact() - Store fact in working memory with FIFO eviction
• getFacts() - Retrieve facts by predicate
• getFactById() - Retrieve specific fact by id
• queryFacts() - Pattern-based fact retrieval

Batch 2E: Analytics Utilities - [x] Complete

• computeColumnBatches() - Columnar layout computation
• mergePartialResults() - Shard result merging
• analyzeTextFeatures() - NLP feature extraction
• extractLoRAPatterns() - LoRA pattern identification
• matchActivityPattern() - Activity sequence matching
• OLAP stub handling and documentation

Quality Metrics (Phase 2 Verified 2026-08-15)

• Functions Implemented: 40/40 (100%)
• Doxygen Coverage: 100% (all functions documented)
• Compiler Warnings: 0 (-Wall -Wextra -Werror clean)
• RAII Compliance: 100% (no manual new/delete)
• Error Handling: Comprehensive validation
• Unit Tests: 80+ tests, all PASS
• Code Coverage: ≥70% across gap functions
• Benchmarks: 6+ benchmarks, <10% regression
• Security: CodeQL clean, no critical issues

Wave Alignment (see root ROADMAP.md § Program Execution Model):

• Wave B (Q3–Q4 2026): OLAP chain optimization, streaming-join performance gates, model-serving reliability, distributed merge diagnostics
• Wave B Exit Criteria: Full analytics chain stable p95/p99 on representative hardware, distributed merge evidence, optional-dependency fallback validated
• Tier 2 Functional Completeness: Not runtime-critical, but performance-sensitive for analytical workloads

In Progress

• hardening of streaming and distributed runtime limits under sustained load (Target: Q3 2026)
  • max_open_windows / max_records_per_window runtime limits added to TumblingWindow, SlidingWindow, HoppingWindow
  • max_open_sessions / max_records_per_session runtime limits added to SessionWindow
  • windows_evicted counter added to WindowStats for all four window types
  • distributed analytics coordinator safety controls (Target: Q3 2026)
    • Circuit breaker pattern (CLOSED/OPEN/HALF_OPEN states) with configurable failure threshold
    • Timeout + recovery with exponential backoff (configurable delays and max backoff)
    • Bounded queue for managing concurrent shard requests with queue depth limits
    • Comprehensive error-path handling for degradation scenarios (fail-closed design)
    • Enhanced diagnostics: CircuitBreakerInfo, state transitions, recovery attempts tracked
    • test_analytics_distributed_coordinator_safety.cpp — 24+ test scenarios (DCS-01..EDGE-02)
  • StreamingRuntimeLimits struct added to analytics_api_contract.h: max_events_per_window, max_window_memory_bytes, BackPressureMode (DROP/BLOCK/SHED) (2026-08-24)
  • test_analytics_streaming_limits_focused.cpp — SRL-01..10 tests added (2026-08-24)
• benchmark and release-gate consolidation for analytics-critical paths (Target: Q3 2026)
  • benchmarks/analytics/bench_streaming_window.cpp added (7 benchmarks covering throughput, eviction, flush latency)
  • benchmarks/analytics/bench_analytics_distributed_coordinator.cpp added (4 release gates: DC-01..DC-04)
• consistency hardening for optional dependency and fallback behavior (Target: Q3 2026)
  • model import integrity guardrails: optional SHA-256 verification API + fail-closed enforcement toggle (require_model_integrity) (Completed 2026-08-19)
  • TF Serving secure transport baseline: HTTPS default + explicit plaintext opt-in (allow_insecure_transport) (Completed 2026-08-19)
  • LLM response schema hardening for fraud/5R/prediction tasks (type/range/bounds checks) (Completed 2026-08-19)
  • prompt injection mitigation in LLM process analyzer: sanitizeUserContent() strips control characters and known injection prefixes from all user-supplied JSON fields before prompt embedding (Completed 2026-08-19)
  • externalize sanitizeUserContent() injection prefix list to a configuration file: LLMConfig::injection_prefix_config_path added; loadInjectionPrefixes() loads from file with 13-pattern fallback; config/analytics/injection_prefixes.txt shipped as default template (Completed 2026-08-19 Batch 6)
  • test_analytics_optional_fallback_focused.cpp — OPF-01..08 tests for MLServingStatus::UNAVAILABLE, AnalyticsErrorCode::STREAM_BACKPRESSURE, and struct composition added (2026-08-24)
  • fail-closed behavior verified for Arrow IPC/Parquet/Feather export (throwArrowUnavailable()) and Arrow Flight in-process fallback (Completed 2026-08-19)
  • multiplication overflow fix in circuit breaker exponential backoff: bit-shift capped to 30 to prevent UB when recovery_attempts ≥ 32 (Completed 2026-08-19)

Planned Features

Short-term (3-6 months)

• strengthen bounded-memory behavior in high-cardinality streaming windows (Completed 2026-08-19)
• extend integration regression coverage for serving and export failure classes (Completed 2026-08-19)
• improve distributed merge diagnostics and operator-facing telemetry (Completed 2026-08-19)

Mid-term (6-12 months)

• add/expand dedicated benchmarks for currently proxy-covered analytics paths (Target: Q1 2027)
• re-baseline analytics latency and throughput envelopes per representative hardware profile (Target: Q1 2027)
• harden cross-cluster security and reliability controls in federated analytics scenarios (Target: Q1 2027)
  • AN1: Wire federated query coordinator — per-shard retry with exponential backoff and ±20% jitter; permanent-failure fast-path skips retry; Config::RetryConfig (max_retries=2, base_delay_ms=50, max_delay_ms=500) (Completed 2026-08-26)
  • AN2: Forecasting model integrity check — CRC-32 computed at serialize() time, verified at deserialize() time; legacy models without checksum pass with THEMIS_WARN; corrupted checksum returns error (Completed 2026-08-26)
  • tests/analytics/test_wave_next_analytics_hardening.cpp — AN1-01..AN1-04, AN2-01..AN2-04 regression tests (Completed 2026-08-26)

Implementation Phases

Phase 1: Design / API Contract

• freeze analytics runtime contracts for critical execution paths (Completed 2026-07-29)
• define explicit failure classes for unsupported dependency/capability states (Completed 2026-07-29)

Phase 2: Core Implementation

• streaming window runtime limits (max_open_windows, max_records_per_window/session, eviction) implemented
• complete remaining runtime hardening in distributed high-load scenarios (Completed 2026-08-08)
  • circuit breaker pattern with state machine
  • bounded queue and backpressure handling
  • exponential backoff recovery mechanism
• [~] align serving/export integration behavior to shared bounded execution policy (Target: Q4 2026)
  • Concrete plan: Define a BoundedExecutionPolicy struct (max_latency_ms, max_concurrent_requests, queue_depth) in analytics_api_contract.h; apply to MLServingClient::infer() (ONNX + TF Serving paths) and AnalyticsExporter::exportToFile() using the existing circuit-breaker infrastructure as the enforcement layer. Tracked as Wave B exit criterion.
  • BoundedExecutionPolicy struct added to analytics_api_contract.h with full field semantics and enforcement contract documentation (Completed 2026-08-19)
  • MLServingClient::infer(req, policy) overload implemented: concurrency (max_concurrent_requests) and timeout (max_latency_ms) enforcement; new TIMEOUT and POLICY_REJECTED status codes added to MLServingStatus (Completed 2026-08-19)
  • IAnalyticsExporter::exportToFile(batch, path, options, policy) non-virtual wrapper implemented: concurrency and timeout enforcement using atomic in-flight counter; POLICY_REJECTED added to ExportStatus (Completed 2026-08-19)
  • BoundedExecutionPolicy default_policy integrated into MLServingConfig: infer(req) routes through infer(req, default_policy) when constrained (Completed 2026-08-19 Batch 6)
  • BoundedExecutionPolicy policy integrated into ExportOptions: used as fallback in exportToFile(…, policy) when the explicit policy is unconstrained (Completed 2026-08-19 Batch 6)
  • 15 targeted regression tests added for policy enforcement paths (BEP-01..BEP-15 in test_analytics_bounded_execution_policy.cpp) (Completed 2026-08-19 Batch 6)

Phase 3: Error Handling and Edge Cases

• standardize fail-closed behavior across optional-backend and degraded states (Completed 2026-08-19)
  • fail-closed policy for insecure TF Serving transport (Completed 2026-08-19)
  • fail-closed policy for model import integrity mismatch (Completed 2026-08-19)
  • prompt injection mitigation in LLM analyzer: sanitizeUserContent() helper (Completed 2026-08-19)
  • fail-closed verified for Arrow IPC/Parquet/Feather export (throwArrowUnavailable()) and Arrow Flight in-process fallback (Completed 2026-08-19)
  • multiplication overflow in circuit breaker backoff fixed: shift capped to 30 bits (Completed 2026-08-19)
• enforce consistent diagnostics for parse/input/state validation failures (Completed 2026-08-19)
  • stricter LLM JSON schema validation for high-risk tasks (Completed 2026-08-19)
  • consistent spdlog::debug late-record diagnostics added to SlidingWindow, SessionWindow, HoppingWindow (TumblingWindow was already done) (Completed 2026-08-19)
  • OLAP input validation diagnostics (empty collection, GroupingSets mode) already present (Verified 2026-08-19)

Phase 4: Tests

• expand focused regressions for high-load streaming, distributed merge, and integration failure paths (Completed 2026-07-29 — test_analytics_contract_hardening_focused.cpp, ANC-01..ANC-16)
• extend deterministic fixture coverage for optional dependency off/on matrixes (Completed 2026-07-29)

Phase 5: Performance and Hardening

• lock benchmark-backed release gates for analytics-critical paths (Completed 2026-07-29 — bench_analytics_release_gates.cpp, ARG-01..ARG-06)
• [~] validate p95/p99 behavior under representative production load profiles (Target: Q4 2026) — ARG-01..ARG-06 + BM_AnalyticsChain_SustainedLoad require representative hardware execution; instrumentation complete, baseline run sandbox-blocked; pending hardware sign-off

Phase 6: Documentation and Acceptance

• core analytics module docs aligned to source-verifiable behavior
• roadmap remains forward-looking while changelog captures historical completion
• analytics_api_contract.h frozen contract header published (Completed 2026-07-29)

Production Readiness Checklist

• core runtime surfaces documented with source verification
• security and failure behavior documented at module level
• mapped benchmark expectations documented
• streaming window runtime limits (max_open_windows, max_records, eviction) implemented
• dedicated streaming window benchmark added (bench_streaming_window.cpp)
• analytics_api_contract.h frozen contract header (Phase 1 closure, 2026-07-29)
• test_analytics_contract_hardening_focused.cpp — ANC-01..ANC-16 (Phase 4 closure, 2026-07-29)
• bench_analytics_release_gates.cpp — ARG-01..ARG-06 gate benchmarks (Phase 5 closure, 2026-07-29)
• distributed analytics coordinator safety controls (Phase 2.2 closure, 2026-08-08)
  • circuit breaker state machine (CLOSED/OPEN/HALF_OPEN)
  • bounded queue and backpressure enforcement
  • exponential backoff recovery with configurable limits
  • fail-closed degradation handling
  • test_analytics_distributed_coordinator_safety.cpp (DCS-01..EDGE-02)
• dedicated benchmark coverage for distributed coordinator safety controls
  • benchmarks/analytics/bench_analytics_distributed_coordinator.cpp — DC-01..DC-04 release gates (2026-08-15)
  • Circuit breaker state transition ≤ 100µs (DC-01)
  • Concurrent merge startup ≤ 500µs p99 (DC-02)
  • Timeout recovery switchover ≤ 1000µs p99 (DC-03)
  • Degraded-mode throughput ≥ 80% of normal (DC-04)
• comprehensive test coverage for distributed coordinator
  • tests/analytics/test_analytics_distributed_coordinator_focused.cpp — CB-01..CB-04, CM-01..CM-04, TO-01..TO-06 tests (2026-08-15)
• BoundedExecutionPolicy integrated into MLServingConfig and ExportOptions (Batch 6, 2026-08-19)
  • MLServingConfig::default_policy — per-client default applied to every infer() call
  • ExportOptions::policy — per-export default used as fallback in exportToFile(…, policy)
  • test_analytics_bounded_execution_policy.cpp — BEP-01..BEP-15 regression tests (2026-08-19)
• injection prefix list externalized from static code to operator-configurable file (Batch 6, 2026-08-19)
  • LLMConfig::injection_prefix_config_path field added
  • loadInjectionPrefixes() helper with built-in 13-pattern fallback
  • config/analytics/injection_prefixes.txt default template shipped

Known Issues and Limitations

• benchmark coverage is still mixed between direct and proxy mappings for some targets.
• behavior and availability remain partially capability-dependent on optional integrations.
• continued hardening is required for cross-cluster/federated scenarios.

Breaking Changes

No breaking module contract planned. Any contract-breaking change requires explicit migration notes and changelog entry before merge.

Program Execution Model — Wave Context

This module is a contributing module in the program-level Wave A → B → C → D execution model. It does not own a primary wave deliverable but must remain release_critical-green throughout all waves and must deliver Wave D operability improvements in Q1 2027. See [[../../ROADMAP.md|ROADMAP]] for the full wave model and exit criteria.

Wave D Contribution for analytics

• Deliver or validate distributed tracing, high-cardinality stress coverage, exporter reliability, and operator remediation hints as applicable to this module (Target: Q1 2027)
• Contribute to or validate long-duration soak test coverage for this module's primary paths (Target: Q1 2027)
• Ensure runbook coverage for operator-critical scenarios in this module (Target: Q1 2027)

Cross-Wave Requirements

• release_critical CI must remain green on develop throughout all waves (Target: ongoing)
• p95/p99 benchmarks must be refreshed on representative hardware before Wave D sign-off (Target: Q1 2027)
• No behavioral regression may be introduced into modules in Wave A/B/C scope from changes in this module.

Program-Level Success Criteria (contribution)

• This module's distributed/acceleration paths fail closed (Target: Q1 2027)
• Benchmark-backed p95/p99 baselines exist on representative hardware (Target: Q1 2027)
• Operator-critical paths have diagnostics, alerts, and runbooks (Target: Q1 2027)