docs/frameworks/GAMIFICATION.md

---
title: "Gamification & Leaderboard System"
version: 3.8.2
lastUpdated: 2026-05-19
---

# Gamification & Leaderboard System

> **Source of truth:** `src/lib/gamification/`, `src/lib/db/gamification.ts`, `src/app/api/gamification/`
> **Last updated:** 2026-05-19 — v3.8.0

OmniRoute includes a local-first gamification layer that rewards users for
engaging with the platform — making requests, switching providers, creating
combos, sharing tokens, and contributing to the community. All state lives in
SQLite; federation with community servers is opt-in and push-based.

The system is designed to be **zero-latency on the hot path** — gamification
events are dispatched fire-and-forget from the request pipeline and never block
an LLM response.

---

## Overview

### Purpose

Increase user engagement and retention by providing visible progress (XP,
levels, badges), social proof (leaderboards), and economic incentives (token
sharing, invite rewards).

### Scope

| Feature           | Description                                                     |
| ----------------- | --------------------------------------------------------------- |
| XP & Levels       | Earn XP per action; level up along a polynomial curve           |
| Badges            | 20+ achievements across 5 categories with 4 rarity tiers        |
| Streaks           | Daily active usage tracking with current/longest streak         |
| Leaderboards      | Global, weekly, monthly, token-sharing, and contribution scopes |
| Token Sharing     | Transfer credits between users via double-entry ledger          |
| Invite & Redeem   | Referral codes with SHA-256 hashed storage                      |
| Community Servers | Federate with external OmniRoute instances                      |
| Anti-Cheat        | Server-side scoring, rate limiting, z-score anomaly detection   |

### Design Principles

1. **Local-first** — all state in SQLite, no external services required.
2. **Non-blocking** — events are fire-and-forget; the LLM response path is
   never delayed by gamification logic.
3. **Server-authoritative** — XP is computed server-side only; clients cannot
   inflate scores.
4. **Privacy-respecting** — leaderboard participation is opt-in; users can
   hide their profile.
5. **Federation-ready** — community servers can push scores via signed API;
   sync is overwrite, not additive.

---

## Architecture

### High-Level Flow

```
Client Request
  → /v1/chat/completions
    → handleChatCore()                      [open-sse/handlers/chatCore.ts]
      → ... (existing pipeline) ...
      → upstream response sent to client
      → setImmediate (fire-and-forget):
        → emitGamificationEvent()           [src/lib/gamification/events.ts]
          → awardXp()                       [src/lib/gamification/xp.ts]
          → updateStreak()                  [src/lib/gamification/streaks.ts]
          → evaluateBadges()                [src/lib/gamification/badges.ts]
          → updateLeaderboard()             [src/lib/gamification/leaderboard.ts]
          → checkAnomalies()                [src/lib/gamification/antiCheat.ts]
```

The event emitter is the single integration point. `chatCore.ts` calls
`emitGamificationEvent()` after the response is sent; the event module fans
out to XP, streak, badge, leaderboard, and anti-cheat subsystems.

### Module Dependency Graph

```
src/lib/gamification/
  events.ts          ← entry point (called from chatCore.ts)
    ├── xp.ts        ← XP calculation & level resolution
    ├── streaks.ts   ← daily active streak tracking
    ├── badges.ts    ← badge criteria evaluation
    ├── leaderboard.ts ← rank computation & SSE broadcasting
    ├── antiCheat.ts ← rate limiting & anomaly detection
    ├── sharing.ts   ← token transfer ledger
    ├── invites.ts   ← invite/redeem code management
    ├── servers.ts   ← community server federation
    └── notifications.ts ← SSE notification stream

src/lib/db/
  gamification.ts    ← all CRUD operations (8 tables)

src/app/api/gamification/
  leaderboard/       ← GET rankings, POST manual refresh
  leaderboard/stream ← SSE real-time updates
  transfer/          ← GET history, POST send tokens
  invite/            ← GET/POST codes, DELETE revoke
  invite/redeem/     ← POST redeem a code
  servers/           ← GET/POST/DELETE community servers
  federation/score/  ← POST push score to server
  federation/leaderboard/ ← GET pull leaderboard from server
  notifications/     ← SSE badge/level-up notifications
  anomalies/         ← GET anomaly reports (admin)
  rotate/            ← POST rotate invite token secrets
```

---

## Data Layer

### Database Tables

All tables live in the main OmniRoute SQLite database, created by migration
`060_create_gamification.sql`. WAL journaling is inherited from the singleton
`getDbInstance()` in `src/lib/db/core.ts`.

```
┌─────────────────────────┐     ┌──────────────────────────┐
│      leaderboard        │     │      user_levels          │
├─────────────────────────┤     ├──────────────────────────┤
│ id            TEXT PK   │     │ api_key_id    TEXT PK    │
│ api_key_id    TEXT      │     │ xp            INTEGER    │
│ scope         TEXT      │     │ level         INTEGER    │
│ score         INTEGER   │     │ title         TEXT       │
│ period        TEXT      │     │ updated_at    TEXT       │
│ updated_at    TEXT      │     └──────────────────────────┘
└─────────────────────────┘
                │
                │ 1:N
                ▼
┌─────────────────────────┐     ┌──────────────────────────┐
│     user_badges         │     │    badge_definitions      │
├─────────────────────────┤     ├──────────────────────────┤
│ id            TEXT PK   │     │ id            TEXT PK    │
│ api_key_id    TEXT      │     │ name          TEXT       │
│ badge_id      TEXT FK   │     │ category      TEXT       │
│ earned_at     TEXT      │     │ rarity        TEXT       │
│ notified      INTEGER   │     │ criteria_type TEXT       │
└─────────────────────────┘     │ criteria      TEXT(JSON) │
                                │ description   TEXT       │
                                │ icon          TEXT       │
                                │ hidden        INTEGER    │
                                └──────────────────────────┘

┌─────────────────────────┐     ┌──────────────────────────┐
│     xp_audit_log        │     │     token_ledger         │
├─────────────────────────┤     ├──────────────────────────┤
│ id            TEXT PK   │     │ id            TEXT PK    │
│ api_key_id    TEXT      │     │ from_key_id   TEXT       │
│ action        TEXT      │     │ to_key_id     TEXT       │
│ xp_awarded    INTEGER   │     │ amount        INTEGER    │
│ metadata      TEXT(JSON)│     │ idempotency_key TEXT UQ  │
│ created_at    TEXT      │     │ created_at    TEXT       │
└─────────────────────────┘     └──────────────────────────┘

┌─────────────────────────┐     ┌──────────────────────────┐
│    invite_tokens        │     │   community_servers      │
├─────────────────────────┤     ├──────────────────────────┤
│ id            TEXT PK   │     │ id            TEXT PK    │
│ api_key_id    TEXT      │     │ name          TEXT       │
│ code          TEXT UQ   │     │ url           TEXT       │
│ token_hash    TEXT      │     │ token_hash    TEXT       │
│ uses          INTEGER   │     │ status        TEXT       │
│ max_uses      INTEGER   │     │ last_sync     TEXT       │
│ created_at    TEXT      │     │ created_at    TEXT       │
│ expires_at    TEXT      │     └──────────────────────────┘
└─────────────────────────┘
```

### Domain Module: `src/lib/db/gamification.ts`

Follows the standard OmniRoute pattern — imports `getDbInstance()` from
`core.ts`, exports typed CRUD functions. No raw SQL in route handlers.

Key functions:

| Function                   | Description                                            |
| -------------------------- | ------------------------------------------------------ |
| `upsertLeaderboardEntry()` | Insert or update score for (api_key_id, scope, period) |
| `getLeaderboard()`         | Paginated rankings for a given scope/period            |
| `getUserLevel()`           | Get or create user level record                        |
| `updateUserLevel()`        | Set XP, level, and title atomically                    |
| `getBadgeDefinitions()`    | All badge definitions (optionally filtered)            |
| `getUserBadges()`          | Badges earned by a user                                |
| `awardBadge()`             | Insert badge earn (idempotent on badge_id)             |
| `logXpAction()`            | Append to xp_audit_log                                 |
| `getXpAuditLog()`          | Paginated audit history for a user                     |
| `insertLedgerEntry()`      | Double-entry transfer (in transaction)                 |
| `getBalance()`             | Sum of received minus sent for a user                  |
| `getTransferHistory()`     | Paginated transfer log                                 |
| `createInviteToken()`      | Insert invite code + hashed token                      |
| `redeemInviteToken()`      | Look up by code, validate, increment uses              |
| `upsertCommunityServer()`  | Register or update a federation server                 |
| `getCommunityServers()`    | List servers for a user                                |
| `deleteCommunityServer()`  | Remove a server registration                           |

---

## XP / Level System

**File:** `src/lib/gamification/xp.ts`

### Level Curve

The XP required to reach level `n` follows a polynomial curve:

```
xp_for_level(n) = floor(100 * n^1.5)
```

| Level | XP to Next | Cumulative XP | Title    |
| ----- | ---------- | ------------- | -------- |
| 1     | 100        | 100           | Beginner |
| 5     | 1,118      | 2,415         | Beginner |
| 10    | 3,162      | 10,523        | Explorer |
| 25    | 12,500     | 86,024        | Explorer |
| 50    | 35,355     | 345,529       | Expert   |
| 75    | 64,952     | 948,683       | Master   |
| 100   | 100,000    | 2,050,000     | Legend   |

### Titles

| Level Range | Title    |
| ----------- | -------- |
| 1 – 9       | Beginner |
| 10 – 24     | Explorer |
| 25 – 49     | Expert   |
| 50 – 74     | Master   |
| 75 – 100    | Legend   |

### XP Rewards

| Action             | XP  | Description                                               |
| ------------------ | --- | --------------------------------------------------------- |
| `request`          | 1   | Per successful LLM request                                |
| `provider_switch`  | 5   | Switching to a different provider                         |
| `combo_create`     | 10  | Creating a new combo configuration                        |
| `combo_use`        | 2   | Using a combo (per target hit)                            |
| `badge_earned`     | 25  | Earning any badge                                         |
| `streak_milestone` | 15  | Reaching a streak milestone (7, 14, 30, 60, 90, 180, 365) |
| `referral`         | 50  | Successfully referring a new user                         |
| `token_share`      | 5   | Sharing tokens with another user                          |
| `daily_login`      | 3   | First request of the day                                  |
| `model_diversity`  | 3   | Using a model not used in the past 7 days                 |
| `compression_use`  | 2   | Using prompt compression                                  |
| `skill_use`        | 2   | Executing a skill via MCP                                 |

### Award Flow

```typescript
export async function awardXp(
  apiKeyId: string,
  action: XpAction,
  metadata?: Record<string, unknown>
): Promise<{ xp: number; level: number; title: string; levelUp: boolean }>;
```

1. Look up `XP_REWARDS[action]` to get the XP amount.
2. Pass through `checkRateLimit()` (anti-cheat: max 1000 XP/min per key).
3. Open a transaction:
   - Read current `user_levels` row.
   - Add XP; recompute level via `levelFromXp(totalXp)`.
   - If level changed, set `levelUp = true`.
   - Update `user_levels` row.
   - Insert into `xp_audit_log`.
4. Return the result. Caller handles notifications.

### Helper: `levelFromXp(totalXp)`

Iterates level 1..100, summing `xp_for_level(n)` until the cumulative XP
exceeds `totalXp`. Returns the highest level whose threshold is met.
This is O(100) — acceptable since levels cap at 100.

---

## Badge System

**File:** `src/lib/gamification/badges.ts`

### Categories

| Category       | Description                        | Example Badges                    |
| -------------- | ---------------------------------- | --------------------------------- |
| `usage`        | Volume-based milestones            | First Request, 1K Requests, 100K  |
| `sharing`      | Token sharing and referrals        | First Share, Generous (10 shares) |
| `contribution` | Community engagement               | Combo Creator, Provider Explorer  |
| `streak`       | Consistency over time              | Week Warrior, Monthly Devoted     |
| `rare`         | Hard-to-get or hidden achievements | Early Adopter, Bug Reporter       |

### Rarities

| Rarity      | Color | Probability Hint |
| ----------- | ----- | ---------------- |
| `common`    | Gray  | Most users       |
| `uncommon`  | Green | Active users     |
| `rare`      | Blue  | Dedicated users  |
| `legendary` | Gold  | Top 1%           |

### Criteria Types

| Type           | Field        | Description                                     |
| -------------- | ------------ | ----------------------------------------------- |
| `action_count` | `count`      | Perform action N times (e.g., 1000 requests)    |
| `streak`       | `days`       | Maintain streak for N consecutive days          |
| `unique_count` | `field`, `n` | Use N unique values (e.g., 10 different models) |
| `rank`         | `scope`, `n` | Reach rank N on a leaderboard scope             |
| `first`        | —            | Be the first to perform an action               |
| `hidden`       | (varies)     | Criteria not shown until earned                 |

Badge definitions are stored in `badge_definitions` as JSON `criteria`:

```json
{
  "type": "action_count",
  "action": "request",
  "count": 1000
}
```

### Evaluation Flow

```
emitGamificationEvent(event)
  → evaluateBadges(apiKeyId, event)
    → getBadgeDefinitions()           # all definitions
    → getUserBadges(apiKeyId)         # already earned (skip)
    → for each unearned badge:
       → matchesCriteria(badge, event, userState)
       → if match: awardBadge(apiKeyId, badgeId)
         → return notification payload
```

Evaluation is **event-driven** — it runs after every gamification event, but
only checks badges whose `criteria.type` aligns with the event action. This
keeps evaluation fast (< 5ms for most events).

### `matchesCriteria(badge, event, userState)`

| Criteria Type  | Check                                              |
| -------------- | -------------------------------------------------- |
| `action_count` | `getActionCount(apiKeyId, action) >= count`        |
| `streak`       | `getCurrentStreak(apiKeyId) >= days`               |
| `unique_count` | `getUniqueCount(apiKeyId, field) >= n`             |
| `rank`         | `getRank(apiKeyId, scope) <= n`                    |
| `first`        | No prior `xp_audit_log` entry for this action type |
| `hidden`       | Delegates to the appropriate sub-check             |

### Built-in Badges (20+)

<details>
<summary>Full badge list</summary>

| Badge               | Category     | Rarity    | Criteria                     |
| ------------------- | ------------ | --------- | ---------------------------- |
| First Steps         | usage        | common    | 1 request                    |
| Getting Warmed Up   | usage        | common    | 100 requests                 |
| Power User          | usage        | uncommon  | 1,000 requests               |
| Centurion           | usage        | rare      | 10,000 requests              |
| OmniPower           | usage        | legendary | 100,000 requests             |
| Provider Hopper     | contribution | common    | Use 5 different providers    |
| Provider Master     | contribution | uncommon  | Use 20 different providers   |
| Combo Architect     | contribution | uncommon  | Create 5 combos              |
| Combo Grandmaster   | contribution | rare      | Create 25 combos             |
| First Share         | sharing      | common    | 1 token transfer             |
| Generous            | sharing      | uncommon  | 10 token transfers           |
| Philanthropist      | sharing      | rare      | Transfer 10,000 tokens total |
| Referrer            | sharing      | common    | 1 successful referral        |
| Network Builder     | sharing      | uncommon  | 10 successful referrals      |
| Week Warrior        | streak       | uncommon  | 7-day streak                 |
| Monthly Devoted     | streak       | rare      | 30-day streak                |
| Unstoppable         | streak       | legendary | 365-day streak               |
| Early Adopter       | rare         | legendary | Join during beta period      |
| Compression Pioneer | rare         | uncommon  | Use compression 100 times    |
| Skill Collector     | rare         | rare      | Use 10 different skills      |
| Model Explorer      | contribution | uncommon  | Use 15 different models      |

</details>

---

## Streak Tracker

**File:** `src/lib/gamification/streaks.ts`

### Data Model

Streaks are stored in the `key_value` table (shared utility table) under
namespaced keys:

| Key                           | Value                            | Description        |
| ----------------------------- | -------------------------------- | ------------------ |
| `gamification:streak:{keyId}` | `{current},{longest},{lastDate}` | Active streak data |

### Logic

```typescript
export async function updateStreak(
  apiKeyId: string
): Promise<{ current: number; longest: number; milestone: boolean }>;
```

1. Read streak record from `key_value`.
2. Parse `{current}`, `{longest}`, `{lastDate}` (ISO date string).
3. If `lastDate === today` — no change (already counted today).
4. If `lastDate === yesterday` — increment `current`; update `longest` if needed.
5. If `lastDate < yesterday` — reset `current = 1` (streak broken).
6. Write updated record.
7. Check milestones: 7, 14, 30, 60, 90, 180, 365 days. If crossed, set
   `milestone = true` (caller awards XP and checks badges).

### Edge Cases

- **Timezone**: streaks use UTC dates (`new Date().toISOString().slice(0, 10)`).
  This is intentional — a single canonical timezone prevents gaming via
  timezone hopping.
- **New users**: no streak record exists; first request creates it with
  `current=1, longest=1, lastDate=today`.
- **Multiple requests per day**: only the first request of the UTC day
  increments the streak.

---

## Leaderboard

**File:** `src/lib/gamification/leaderboard.ts`

### Scopes

| Scope           | Period  | Description                                   |
| --------------- | ------- | --------------------------------------------- |
| `global`        | `all`   | All-time cumulative XP                        |
| `weekly`        | `week`  | XP earned in current UTC week (Mon-Sun)       |
| `monthly`       | `month` | XP earned in current UTC month                |
| `tokens_shared` | `all`   | Total tokens transferred to others            |
| `contributions` | `all`   | Combos created + providers used + skills used |

### Rank Computation

Ranks are **computed at read time**, not stored. This avoids stale rank data
and eliminates the need for periodic rank recalculation jobs.

```typescript
export async function getLeaderboard(
  scope: LeaderboardScope,
  period: string,
  limit: number,
  offset: number
): Promise<{ entries: LeaderboardEntry[]; total: number }>;
```

Query pattern:

```sql
SELECT api_key_id, score,
       RANK() OVER (ORDER BY score DESC) as rank
FROM leaderboard
WHERE scope = ? AND period = ?
ORDER BY score DESC
LIMIT ? OFFSET ?
```

### Period Rotation

Weekly and monthly leaderboards rotate automatically:

1. **Archive**: at period boundary, copy current entries to
   `leaderboard_archive` with the period label.
2. **Reset**: delete entries for the expired period.
3. **Trigger**: checked on every `updateLeaderboard()` call; the first request
   of a new period triggers the rotation.

This ensures weekly boards reset every Monday 00:00 UTC and monthly boards
reset on the 1st of each month.

### SSE Real-Time Updates

**Endpoint:** `GET /api/gamification/stream`

```
Client → GET /api/gamification/stream
  → SSE connection established
  → Server sends top-10 leaderboard snapshot immediately
  → Every 5 seconds: push updated top-10 if changed
  → Every 15 seconds: heartbeat comment (": heartbeat\n\n")
  → Client disconnects → cleanup (remove listener)
```

Event format:

```
event: leaderboard
data: {"scope":"global","entries":[...]}

event: leaderboard
data: {"scope":"weekly","entries":[...]}

: heartbeat
```

The SSE manager tracks connected clients per scope and only sends updates
when the leaderboard data has actually changed since the last push.

---

## Token Sharing

**File:** `src/lib/gamification/sharing.ts`

### Double-Entry Ledger

Every transfer creates two rows in `token_ledger`:

| Row    | `from_key_id` | `to_key_id` | `amount` |
| ------ | ------------- | ----------- | -------- |
| Debit  | sender        | receiver    | +amount  |
| Credit | receiver      | sender      | -amount  |

Wait — the convention is:

| Row     | `from_key_id` | `to_key_id` | `amount` | Meaning             |
| ------- | ------------- | ----------- | -------- | ------------------- |
| Send    | sender        | receiver    | +amount  | Outflow from sender |
| Receive | receiver      | sender      | +amount  | Inflow to receiver  |

Balance is computed as:

```sql
SELECT
  COALESCE(SUM(CASE WHEN to_key_id = ? THEN amount ELSE 0 END), 0)
  - COALESCE(SUM(CASE WHEN from_key_id = ? THEN amount ELSE 0 END), 0)
  AS balance
FROM token_ledger
WHERE from_key_id = ? OR to_key_id = ?
```

### Transfer Flow

```typescript
export async function transferTokens(
  fromKeyId: string,
  toKeyId: string,
  amount: number,
  idempotencyKey: string
): Promise<{ success: boolean; balance: number }>;
```

1. **Validate**: `amount > 0`, `fromKeyId !== toKeyId`.
2. **Idempotency**: check if `idempotency_key` already exists in ledger.
   If yes, return cached result.
3. **Transaction** (single SQLite transaction):
   a. Compute sender balance.
   b. If `balance < amount`, abort (insufficient funds).
   c. Insert send row (`from=sender, to=receiver, amount`).
   d. Insert receive row (`from=receiver, to=sender, amount`).
4. **Rate limit**: check transfer rate for sender (max 10 transfers/min).
5. **Event**: emit `token_share` gamification event for XP + badge evaluation.
6. Return `{ success: true, balance: newBalance }`.

### Rate Limiting

- Max 10 transfers per minute per API key.
- Max 10,000 tokens per single transfer.
- Max 100,000 tokens transferred per day per API key.

---

## Invite & Redeem Tokens

**File:** `src/lib/gamification/invites.ts`

### Code Format

- **Code**: 8-character alphanumeric (e.g., `A3K9-X7M2`), human-readable,
  displayed to the user.
- **Token**: 32-byte random token, stored as SHA-256 hash. Used for
  programmatic redemption (e.g., URL links).

### Storage

| Column       | Value                        |
| ------------ | ---------------------------- |
| `code`       | `A3K9X7M2` (unique, indexed) |
| `token_hash` | SHA-256(raw_token)           |

The raw token is returned to the user exactly once at creation time. OmniRoute
never stores or displays it again — only the hash persists.

### Self-Referral Prevention

When a user redeems a code, the system checks:

1. The code belongs to a different `api_key_id`.
2. The redeeming user has not previously redeemed any code from the same
   referrer (joins on `invite_tokens` + redemption log).

If either check fails, the redemption is rejected with a clear error message.

### Expiry & Limits

- Default `max_uses`: 10 (configurable at creation).
- Default `expires_at`: 30 days from creation.
- Expired or exhausted codes return HTTP 410 Gone.

---

## Community Server Federation

**File:** `src/lib/gamification/servers.ts`

### Connect

A community server is registered via an invite token issued by the remote
server. The local instance:

1. Receives the invite token (e.g., pasted into dashboard).
2. Calls `POST /api/gamification/federation/leaderboard` on the remote server
   to validate the token and fetch the current leaderboard.
3. Stores the server record with `status: connected`.

### Sync Model

Federation uses **overwrite sync**, not additive:

```
Local Instance                Community Server
     │                              │
     ├── push score ───────────────►│  POST /federation/score
     │   { api_key_id, score }      │  (server validates token hash)
     │                              │
     ├── pull leaderboard ─────────►│  GET /federation/leaderboard
     │◄── top-N entries ────────────┤  (overwrites local cache)
     │                              │
     └── health check ─────────────►│  GET /federation/health
         (every 60s, timeout 5s)    │
```

### Auth

Federation requests include:

```
Authorization: Bearer <raw_token>
X-Federation-Version: 1
```

The remote server hashes the token and looks up the matching
`community_servers` row. This avoids transmitting the stored hash.

### Health Monitoring

Each server record tracks:

| Field       | Description                            |
| ----------- | -------------------------------------- |
| `status`    | `connected`, `degraded`, `unreachable` |
| `last_sync` | ISO timestamp of last successful sync  |
| `failures`  | Consecutive health check failures      |

After 5 consecutive failures, status changes to `unreachable` and sync is
paused until a manual health check succeeds.

---

## Anti-Cheat

**File:** `src/lib/gamification/antiCheat.ts`

### Server-Side Scoring

All XP calculations happen in `src/lib/gamification/xp.ts`. Clients never
submit a score — they submit actions, and the server computes XP. The
`leaderboard.score` column is only writable by server-side code.

### Rate Limiting

| Limit                 | Value   | Scope        |
| --------------------- | ------- | ------------ |
| Max XP per minute     | 1,000   | Per API key  |
| Max transfers per min | 10      | Per API key  |
| Max transfer amount   | 10,000  | Per transfer |
| Max daily transfers   | 100,000 | Per API key  |

Rate limits use an in-memory sliding window (same pattern as
`RateLimitManager` in `open-sse/services/`). Falls back to SQLite-backed
counters if the process restarts.

### Z-Score Anomaly Detection

For each API key, the system maintains a rolling 7-day window of XP earned per
hour. On each XP award:

1. Compute the user's current hourly XP rate.
2. Compute the population mean and standard deviation.
3. Calculate `z = (user_rate - mean) / stddev`.
4. If `z > 3.0` (3 standard deviations), flag as anomaly.

Anomalies are logged to `xp_audit_log` with `action = 'anomaly_detected'`
and surfaced on the admin dashboard.

### Audit Trail

Every XP award, transfer, badge earn, and anomaly detection is logged to
`xp_audit_log` with:

| Field        | Description                                    |
| ------------ | ---------------------------------------------- |
| `api_key_id` | Who                                            |
| `action`     | What happened (xp_award, transfer, anomaly, …) |
| `xp_awarded` | Amount (0 for non-XP events)                   |
| `metadata`   | JSON with context (action type, target, …)     |
| `created_at` | When (ISO 8601)                                |

Admins can query the full audit trail via `GET /api/gamification/anomalies`.

---

## API Routes

All routes follow the standard OmniRoute pattern:

```
Route → CORS preflight → Body validation (Zod) → Auth (extractApiKey)
  → Handler
```

### Endpoints

| Method | Path                                       | Description                                 | Auth       |
| ------ | ------------------------------------------ | ------------------------------------------- | ---------- |
| GET    | `/api/gamification/leaderboard`            | Get leaderboard (scope, period, pagination) | Optional   |
| POST   | `/api/gamification/leaderboard`            | Force refresh leaderboard cache             | Required   |
| GET    | `/api/gamification/stream`                 | SSE real-time leaderboard updates           | Optional   |
| GET    | `/api/gamification/transfer`               | Get transfer history (pagination)           | Required   |
| POST   | `/api/gamification/transfer`               | Send tokens to another user                 | Required   |
| GET    | `/api/gamification/invite`                 | List my invite codes                        | Required   |
| POST   | `/api/gamification/invite`                 | Generate a new invite code                  | Required   |
| DELETE | `/api/gamification/invite`                 | Revoke an invite code                       | Required   |
| POST   | `/api/gamification/invite/redeem`          | Redeem an invite code                       | Required   |
| GET    | `/api/gamification/servers`                | List community servers                      | Required   |
| POST   | `/api/gamification/servers`                | Connect to a community server               | Required   |
| DELETE | `/api/gamification/servers`                | Disconnect from a community server          | Required   |
| POST   | `/api/gamification/federation/score`       | Push score to remote server                 | Federation |
| GET    | `/api/gamification/federation/leaderboard` | Pull leaderboard from remote                | Federation |
| GET    | `/api/gamification/notifications`          | SSE badge/level-up notifications            | Required   |
| GET    | `/api/gamification/anomalies`              | View anomaly reports (admin)                | Admin      |
| POST   | `/api/gamification/rotate`                 | Rotate invite token secrets                 | Required   |

### Request/Response Examples

**POST /api/gamification/transfer**

```json
// Request
{
  "to": "recipient-api-key-id",
  "amount": 500,
  "idempotencyKey": "uuid-v4"
}

// Response 200
{
  "success": true,
  "transfer": {
    "id": "txn-uuid",
    "from": "sender-api-key-id",
    "to": "recipient-api-key-id",
    "amount": 500,
    "createdAt": "2026-05-19T12:00:00.000Z"
  },
  "balance": 2500
}

// Response 400 (insufficient funds)
{
  "error": "Insufficient balance",
  "balance": 200,
  "requested": 500
}
```

**GET /api/gamification/leaderboard?scope=weekly&limit=10**

```json
{
  "scope": "weekly",
  "period": "2026-W20",
  "entries": [
    {
      "rank": 1,
      "apiKeyId": "key-uuid",
      "displayName": "User***1234",
      "score": 15230,
      "level": 42,
      "title": "Expert"
    }
  ],
  "total": 847,
  "updatedAt": "2026-05-19T12:00:00.000Z"
}
```

---

## MCP Tools (8)

Registered in `open-sse/mcp-server/` alongside existing tools. Scoped under
the `gamification` permission scope.

| Tool                       | Description                           | Input Schema                 |
| -------------------------- | ------------------------------------- | ---------------------------- | --------- |
| `gamification_leaderboard` | Get leaderboard for a scope/period    | `{ scope, period?, limit? }` |
| `gamification_rank`        | Get caller's rank and neighbors       | `{ scope }`                  |
| `gamification_profile`     | Get XP, level, title, streak summary  | `{}`                         |
| `gamification_badges`      | List earned badges or all definitions | `{ earned?: boolean }`       |
| `gamification_transfer`    | Send tokens to another user           | `{ to, amount }`             |
| `gamification_invite`      | Generate or list invite codes         | `{ action: "create"          | "list" }` |
| `gamification_servers`     | List or connect community servers     | `{ action, token? }`         |
| `gamification_anomalies`   | View anomaly reports (admin scope)    | `{ limit?, since? }`         |

---

## Dashboard Pages

### `/dashboard/leaderboard`

- Podium display (top 3 with avatars and XP).
- Scope selector: Global / Weekly / Monthly / Tokens Shared / Contributions.
- Paginated table (25 per page) with rank, name, score, level, title.
- SSE real-time updates — rank changes animate in.
- Current user highlighted in the table with a "Your Rank" sticky row.

### `/dashboard/profile`

- XP progress bar with current level and next-level threshold.
- Title badge displayed prominently.
- Badge gallery — earned badges with earn date, unearned badges grayed out
  (hidden badges show "???" until earned).
- Streak counter with flame icon; streak calendar (last 30 days).
- XP history chart (daily XP over last 30 days).

### `/dashboard/tokens`

- Token balance (prominent, top of page).
- Transfer form: recipient, amount, confirm dialog.
- Transfer history table with filters (sent/received/all).
- Invite section: active codes, generate new, share link.
- Community servers: list with health status, connect/disconnect.

### `/dashboard/gamification/admin`

- Anomaly list with severity, user, timestamp, z-score.
- Audit log viewer with filters (action type, user, date range).
- System stats: total XP awarded, active users, badge earn rates.
- Federation server health overview.

---

## Pipeline Integration

### Integration Point

Gamification hooks into the request pipeline at a single point in
`open-sse/handlers/chatCore.ts`:

```typescript
// After response is sent to client:
setImmediate(() => {
  emitGamificationEvent({
    type: "request.completed",
    apiKeyId,
    metadata: {
      provider: selectedProvider,
      model: selectedModel,
      comboId: resolvedCombo?.id,
      compressionUsed: compressionStats?.applied,
      skillUsed: skillExecution?.name,
    },
  }).catch(() => {
    // Fire-and-forget: log but never propagate to client
  });
});
```

### Event Types

| Event Type          | When Emitted                             |
| ------------------- | ---------------------------------------- |
| `request.completed` | Successful LLM response sent             |
| `provider.switch`   | Provider changed (combo fallback counts) |
| `combo.created`     | New combo configuration saved            |
| `combo.used`        | Combo target successfully hit            |
| `badge.earned`      | Badge evaluation found a match           |
| `streak.milestone`  | Streak threshold crossed                 |
| `transfer.sent`     | Token transfer completed                 |
| `referral.redeemed` | Invite code successfully redeemed        |
| `compression.used`  | Prompt compression applied               |
| `skill.executed`    | Skill execution completed                |
| `model.first_use`   | Model not used in past 7 days            |

### Non-Blocking Guarantee

The `setImmediate` + `.catch(() => {})` pattern ensures:

1. The response is fully sent before gamification runs.
2. Gamification errors never surface to the client.
3. The event processing runs in the next microtask, not inline.

---

## Security

### Threat Model

| Threat                   | Mitigation                                                          |
| ------------------------ | ------------------------------------------------------------------- |
| Score inflation          | Server-side XP computation only; clients submit actions, not scores |
| Replay attacks           | Idempotency keys on transfers; audit log dedup                      |
| Transfer fraud           | Double-entry ledger; atomic transactions; rate limits               |
| Self-referral            | Cross-check `api_key_id` on redemption                              |
| Leaderboard manipulation | Z-score anomaly detection; admin anomaly dashboard                  |
| Federation token theft   | SHA-256 hashed storage; raw token shown once only                   |
| Brute force invite codes | Rate limiting on redemption endpoint; 8-char entropy                |
| XSS in display names     | Display names sanitized; leaderboard entries escaped                |
| Timing attacks on hashes | `crypto.timingSafeEqual` for token hash comparison                  |

### Auth Requirements

- **Public** (no auth): `GET /leaderboard`, `GET /stream` (read-only
  leaderboards).
- **API key required**: all write operations, profile, transfers, invites.
- **Admin only**: anomaly dashboard, audit log viewer.
- **Federation**: separate auth path using raw token in `Authorization`
  header, validated against stored SHA-256 hash.

---

## Testing

### Test Files

All tests use the Node.js native test runner (`node --import tsx/esm --test`).

| Test File                                     | Covers                                  | Tests |
| --------------------------------------------- | --------------------------------------- | ----- |
| `tests/unit/gamification/xp.test.ts`          | XP calculation, level curve, titles     | 8     |
| `tests/unit/gamification/badges.test.ts`      | Badge criteria matching, awarding       | 10    |
| `tests/unit/gamification/streaks.test.ts`     | Streak logic, milestones, edge cases    | 7     |
| `tests/unit/gamification/leaderboard.test.ts` | Rank computation, pagination, rotation  | 8     |
| `tests/unit/gamification/sharing.test.ts`     | Transfers, balance, idempotency         | 9     |
| `tests/unit/gamification/invites.test.ts`     | Create, redeem, expiry, self-referral   | 7     |
| `tests/unit/gamification/antiCheat.test.ts`   | Rate limits, z-score, audit logging     | 6     |
| `tests/unit/gamification/events.test.ts`      | Event emission, fan-out, error handling | 5     |

### Running Tests

```bash
# All gamification tests
node --import tsx/esm --test tests/unit/gamification/*.test.ts

# Single test file
node --import tsx/esm --test tests/unit/gamification/xp.test.ts
```

### Coverage Requirements

Per `CONTRIBUTING.md` — all new modules must have:

- Branch coverage >= 80%.
- Every public function tested at least once.
- Error paths tested (insufficient balance, expired codes, rate limits).

---

## File Structure

```
src/
  lib/
    db/
      migrations/
        060_create_gamification.sql    # All 8 tables + indexes
      gamification.ts                  # Domain CRUD module
    gamification/
      xp.ts                           # XP calculation, level curve, titles
      badges.ts                       # Badge definitions, criteria, evaluation
      streaks.ts                      # Daily streak tracking
      leaderboard.ts                  # Rank computation, SSE, rotation
      antiCheat.ts                    # Rate limiting, z-score, audit
      sharing.ts                      # Token transfer ledger
      invites.ts                      # Invite/redeem codes
      servers.ts                      # Community server federation
      events.ts                       # Event emitter (integration point)
      notifications.ts                # SSE notification stream
  app/
    api/
      gamification/
        leaderboard/route.ts          # GET/POST leaderboard
        leaderboard/stream/route.ts   # SSE real-time updates
        transfer/route.ts             # GET/POST transfers
        invite/route.ts               # GET/POST/DELETE invite codes
        invite/redeem/route.ts        # POST redeem code
        servers/route.ts              # GET/POST/DELETE servers
        federation/score/route.ts     # POST push score
        federation/leaderboard/route.ts # GET pull leaderboard
        notifications/route.ts        # SSE notifications
        anomalies/route.ts            # GET anomaly reports
        rotate/route.ts               # POST rotate secrets
    (dashboard)/
      dashboard/
        leaderboard/page.tsx           # Rankings page
        profile/page.tsx               # XP/badges/streaks page
        tokens/page.tsx                # Balance/transfers/invites page
        gamification/admin/page.tsx    # Admin anomaly monitoring
  shared/
    constants/
      gamification.ts                  # XP_REWARDS, TITLES, BADGE_DEFS, LIMITS

tests/
  unit/
    gamification/
      xp.test.ts
      badges.test.ts
      streaks.test.ts
      leaderboard.test.ts
      sharing.test.ts
      invites.test.ts
      antiCheat.test.ts
      events.test.ts

docs/
  frameworks/
    GAMIFICATION.md                    # This document
```

---

## Migration Strategy

### Phase 1: Backend Core (PR 1)

- Migration `060_create_gamification.sql` (8 tables).
- `src/lib/db/gamification.ts` (domain module).
- `src/lib/gamification/xp.ts`, `streaks.ts`, `events.ts`.
- Integration point in `chatCore.ts`.
- Unit tests for XP, streaks, events.

### Phase 2: Badges & Leaderboard (PR 2)

- `src/lib/gamification/badges.ts`, `leaderboard.ts`.
- Badge definitions in constants.
- Leaderboard API routes + SSE stream.
- Unit tests for badges, leaderboard.

### Phase 3: Sharing & Invites (PR 3)

- `src/lib/gamification/sharing.ts`, `invites.ts`, `antiCheat.ts`.
- Transfer + invite API routes.
- Unit tests for sharing, invites, anti-cheat.

### Phase 4: Federation & Dashboard (PR 4)

- `src/lib/gamification/servers.ts`, `notifications.ts`.
- Federation API routes.
- Dashboard pages (leaderboard, profile, tokens, admin).
- MCP tools registration.

---

## Future Considerations

- **Seasonal events**: time-limited badge sets and leaderboard seasons.
- **Team leaderboards**: group users by organization or combo.
- **XP multipliers**: boost XP during promotional periods.
- **Achievement sharing**: generate shareable badge cards (OpenGraph images).
- **Mobile push**: webhook-based notifications for badge/level events.
- **Leaderboard API**: public API for third-party integrations.