Hermes Achievements Performance Spec (Post-Hackathon)

Status: Draft (no code changes yet) Owner: hermes-achievements plugin Scope: dashboard/plugin_api.py + dashboard/dist/index.js request behavior Decision: Drop /overview and top-banner slots; keep only Achievements tab data path.

---

1) Problem Statement

Current plugin endpoints /achievements and /overview both execute a full history recomputation (evaluate_all()), which performs a full SessionDB scan each request.

Observed on this machine/repo:

• ~83 sessions
• ~7,125 messages
• ~3,623 tool calls
• evaluate_all() ~13–16s per call
• /achievements ~13–15s per call
• /overview ~12–15s per call
• Overlap between endpoints increases perceived wait.

Given current product direction, /overview and cross-tab top-banner slots are not needed.

---

2) Goals

• Keep achievement correctness unchanged.
• Keep all Achievements-tab UX/data (unlocked/discovered/secrets/highest/latest/cards).
• Remove unused summary path (/overview) and slot wiring.
• Make Achievements tab faster by avoiding duplicate endpoint pathways.
• Ensure at most one heavy scan can run at a time.

Non-goals (phase 1):

• Rewriting achievement rules.
• Changing badge semantics/states.

---

3) Endpoint Semantics (Target)

GET /api/plugins/hermes-achievements/achievements

Single source endpoint for Achievements UI. Returns full payload used by the tab:

• achievements
• unlocked_count
• discovered_count
• secret_count
• total_count
• error

POST /api/plugins/hermes-achievements/rescan (optional)

Manual refresh trigger. Prefer async trigger + immediate status response.

GET /api/plugins/hermes-achievements/scan-status (optional new)

Reports scan state for UX/ops.

Removed

• GET /api/plugins/hermes-achievements/overview

---

4) UI Scope (Target)

Keep:

• Achievements page/tab (/achievements in plugin tab manifest)
• All existing Achievements tab stats/cards/filters

Remove:

• Top-banner summary slot components using sessions:top and analytics:top
• Any frontend call path to /overview

---

5) Runtime State Machine (for /achievements)

• FRESH: cached snapshot age <= TTL
• STALE: snapshot exists but expired
• SCANNING: background recompute running
• FAILED: last recompute failed, last good snapshot still served

Rules:

1. FRESH -> serve immediately.
2. STALE + not scanning -> serve stale snapshot immediately and launch background refresh.
3. SCANNING -> do not start another scan; join single-flight in-flight job.
4. No snapshot yet -> allow one blocking bootstrap scan.

---

6) Caching & Invalidation

Phase 1

• In-memory cache + persisted snapshot file.
• TTL: 60–180 seconds (configurable).
• Single-flight dedupe for scan requests.
• Persist plugin data under:
  • ~/.hermes/plugins/hermes-achievements/scan_snapshot.json

Phase 2

• Incremental scan checkpoints with per-session fingerprints.
• Persist checkpoint data under:
  • ~/.hermes/plugins/hermes-achievements/scan_checkpoint.json
• Checkpoint stores, per session:
  • session_id
  • fingerprint (updated_at, message_count, or hash)
  • cached per-session contribution used for aggregate recomposition
• Scan policy:
  • First run: full scan and materialize snapshot + checkpoint.
  • Next runs: process only new/changed sessions, reuse unchanged contributions.
• Full rebuild only on:
  • schema/version change
  • checkpoint corruption
  • explicit full rescan

---

7) Frontend Contract

• Achievements tab requests /achievements once on mount.
• No slot-based summary fetches.
• If response says is_stale=true, UI may display “Updating in background”.
• Avoid duplicate mount-triggered calls and cancel stale requests on navigation.

---

8) SLO Targets

• /achievements p95 < 1s (cached)
• Max concurrent heavy scans: 1
• Background refresh should not block UI

---

9) Observability Requirements

Track:

• scan count
• scan duration avg/p95
• dedupe hit count (joined in-flight scans)
• stale-served count
• failures + last error

Expose minimal diagnostics in /scan-status.

---

10) Backward Compatibility

• Keep /achievements response shape backward-compatible.
• Removing /overview is acceptable because slot UI is intentionally removed.
• If temporary compatibility is needed, /overview can return static deprecation response for one release.

---

11) Risks

• Stale data confusion -> mitigate with generated_at and explicit refresh status.
• Cache invalidation bugs -> start with conservative TTL + manual rescan.
• Concurrency bugs -> protect scan section with lock/single-flight guard.
• Session mutation edge cases -> use per-session fingerprint invalidation (not global timestamp only).

---

12) Persistence Files (Explicit)

Plugin state directory:

• ~/.hermes/plugins/hermes-achievements/

Files:

• state.json (existing): unlock tracking
• scan_snapshot.json (new): latest materialized achievements payload
• scan_checkpoint.json (new): per-session fingerprints + contributions for incremental refresh