rust analytics roadmap

Rust analytics roadmap

Kognitika is moving toward Rust incrementally. The immediate objective is not a full backend rewrite, but a real production Rust domain that directly improves the product: reliable analysis of interactions across every cognitive module and longitudinal tracking of skill changes.

Current reality

Area	Current production owner	Rust status
Web UI and trainer engines	React + TypeScript	No UI rewrite planned
Immediate browser metrics	JavaScript/TypeScript Web Worker	Browser WASM exists as a measured option, not production authority
Full-session analysis	TypeScript services	crates/kognitika-core implements native + WASM AnalyzeSession parity core
API, auth, Brain ID, game saves	Express + Socket.io + Prisma	Remains in Express during the first migration phases
Persistence and trend APIs	PostgreSQL + Prisma + Express	Existing foundation, but event completeness and metric versioning must improve
OpenAPI	Planned in issue #138	Must be implementation-neutral for Express and future Rust endpoints

The existing Node and browser benchmarks confirmed deterministic Rust/WASM parity. They also showed that Rust/WASM is not automatically faster for small browser sessions. Worker isolation improves frame responsiveness, so browser WASM remains a separate benchmark-driven choice. The strongest first production boundary is native server-side analytics.

Target architecture

All cognitive modules
  -> versioned canonical interaction events
  -> Express ownership/privacy validation
  -> PostgreSQL durable analytics outbox
       -> TypeScript authority/fallback
       -> native Rust/Axum analyzer
  -> versioned SessionAnalyticsSummary
  -> baseline-aware longitudinal Rust projections
  -> existing authenticated Express API
  -> web and mobile clients

Rust begins as a stateless analyzer. It does not initially own authentication, public routing, Prisma migrations, or game-save transactions. This keeps the migration reversible and avoids two services owning the same data.

Rollout model

1. TS-only baseline: measure valid job coverage, latency, failure rate, and queue lag.
2. Shadow: TypeScript remains authoritative; Rust computes the same job and only privacy-safe field diffs and operational metrics are recorded.
3. Canary: Rust becomes primary for deterministic cohorts, for example 1% → 5% → 25% → 50%.
4. Rust-primary: Rust handles 100% of eligible analytics jobs; TypeScript remains a circuit-breaker fallback for at least one stable release.
5. Longitudinal analytics: robust personal baselines, uncertainty, and versioned skill projections move to Rust.
6. Next backend domain: selected through an evidence-based migration scorecard, not by rewrite percentage.

Game saving, XP, authentication, and user-visible completion must never depend on Rust analyzer availability.

Roadmap issues

• #139 — Rust cognitive analytics roadmap
• #140 — Canonical events for every cognitive module
• #141 — Durable Rust/TS analytics outbox
• #142 — Internal Axum sidecar on kognitika-core
• #143 — Shadow and canary rollout with TS fallback
• #144 — Longitudinal cognitive skill dynamics in Rust
• #145 — Scorecard for the next backend migration

Related existing work: #48, #93, #112, and #138.

Longitudinal skill interpretation

A single raw average across different trainers is not a valid cognitive-development measure. The implementation should proceed in this order:

1. trajectories within the same module, module version, and comparable difficulty;
2. robust personal baseline and minimum sample thresholds;
3. separate speed and accuracy trends to expose the speed-accuracy trade-off;
4. sample count, coverage quality, and uncertainty in every trend response;
5. explicit policies for abandoned, suspicious, incomplete, and outlier sessions;
6. only then an experimental versioned mapping from module metrics to broader cognitive domains.

Kognitika measures performance inside training tasks. It must not claim to diagnose intelligence, illness, or medical cognitive status without a separate scientific, legal, and product validation process.

Backend migration gates

A new bounded context should move to Rust only when:

• the preceding Rust domain has been stable at 100% load for at least 30 days;
• its public/data contract is versioned and covered by parity tests;
• observability, canary, automatic fallback, and rollback drills are in place;
• profiling shows a performance, reliability, security, or product-capability reason;
• migration reduces ownership duplication instead of creating a second writer;
• the team can operate the Rust service in production.

Preferred order after session analytics:

1. batch reprocessing and anti-fraud kernels;
2. longitudinal aggregation and recommendations;
3. deterministic generators and scoring;
4. isolated stateless HTTP APIs;
5. authentication, Brain ID ownership, game transactions, Socket.io, and general CRUD last.

OpenAPI and the Rust transition

OpenAPI is not tied to JavaScript or Rust. It is the external HTTP contract. Issue #138 should therefore produce a specification that is independent of Express handler comments wherever practical, validated in CI, and reusable for generated clients and compatibility tests.

Until #138 is implemented and verified, /api/docs and /api/docs.json are planned endpoints, not production promises.

Production

• Site: https://kognitika.ru
• Health: https://kognitika.ru/api/health
• Repository: github.com/xodapi/kognitika

All normal changes follow repository-first deployment. Direct production patches remain forbidden outside the documented emergency process.