zesdex/docs/CODEMAPS/data.md

# Data & Persistence

## State Runtime (TUI)

State TUI yang berjalan di memori adalah `AppStateRest` (`apps/interfaces/tui/src/state.rs`).

### TranscriptCache

```rust
pub struct TranscriptCache {
    pub messages: VecDeque<ChatMessageDisplay>,  // O(1) eviction
    pub max_lines: usize,                        // default: 200
    pub dirty: bool,                             // perlu rebuild cache?
}
```

Saat `dirty=true`, `pre_render_chat()` rebuild `display_lines_cache` (render markdown semua pesan) sebelum frame berikutnya.

### SessionRuntime

```rust
pub struct SessionRuntime {
    pub messages: Vec<ChatMessage>,   // history untuk LLM context
    pub usage: UsageStats,            // token counting akumulasi
    pub session_start: i64,           // unix ms saat sesi dimulai
    pub hive_mind_converged: bool,    // flag selesai hive mind
}
```

## Context Window

`resolve_context_window()` di `state.rs`:
1. Ambil `settings.max_tokens` jika ada dan > 0
2. Fallback ke **256.000 token** (default)

Token dihitung lazily via `count_tokens()` (tiktoken `cl100k_base`, fallback `len/4`), di-cache di `AppStateRest::cached_token_count`, hanya dihitung ulang saat `token_count_dirty=true`.

## Persistence di Disk

Semua data disimpan di **platform data directory**:
- **Linux**: `~/.local/share/zesdex/`
- **macOS**: `~/Library/Application Support/zesdex/`

```
~/.local/share/zesdex/
├── settings.json              # User settings (provider, model, max_tokens, dll)
├── sessions/
│   └── <uuid>/
│       ├── session.json       # Metadata sesi
│       ├── messages.jsonl     # Message log (append-only)
│       └── .lock              # Lock file (cegah concurrent access)
├── memories/
│   └── *.md                   # Memory files dengan frontmatter
├── lessons/
│   └── *.md                   # Lesson files (output dari learning system)
└── worktrees/                 # Git worktree per sesi (isolasi perubahan)
```

### settings.json

```json
{
  "provider": "openai",
  "model": "gpt-4o",
  "max_tokens": 256000,
  "temperature": 0.7,
  "concise_output": false
}
```

Diload via `JsonSettingsRepository::load()`, disimpan kembali saat TUI keluar (`state.save_settings()`).

### Memory Files

Format markdown dengan YAML frontmatter:
```markdown
---
name: prefer-early-return
type: feedback
description: Selalu gunakan early return untuk mengurangi nesting
---

Ketika menulis fungsi, gunakan early return/guard clauses daripada deep nesting.
```

Types: `user`, `feedback`, `project`, `reference`

### Lesson Files

Hasil dari learning system, disimpan di `lessons/`:
- Satu file per lesson
- Plain markdown, dibaca oleh overlay `Learning`
- Bisa di-accept/reject dari TUI

## SQLite (Message Log)

`rusqlite` dengan fitur `bundled` (tidak perlu install SQLite terpisah):
- Per-session database di `sessions/<uuid>/messages.db`
- Table `messages`: `id`, `session_id`, `role`, `content`, `timestamp`, `tokens`
- Table `sessions`: `id`, `metadata`, `created_at`

## IPC Protocol (Daemon Mode)

Daemon dan client berkomunikasi via **Unix domain socket**:

```
~/.local/share/zesdex/daemon.sock
```

Frame format:
```
[4 bytes BE: payload length][JSON payload]
```

Message types:
- `Action` — client kirim aksi ke daemon
- `StateSnapshot` — daemon kirim snapshot state ke client
- `Ping/Pong` — keepalive

## Edit History

Agent mencatat setiap mutasi file ke event log internal:
- Tool `write`/`edit`/`delete` merekam path, bytes delta, timestamp
- Digunakan oleh subagent review untuk audit trail

## TurnEvent Queue

Agent berjalan di background thread dan mengirim events ke TUI via `Arc<Mutex<VecDeque<TurnEvent>>>`:

| Event | Payload | Efek di TUI |
|-------|---------|-------------|
| `AssistantMessage(msg)` | `ChatMessage` | Push ke transcript |
| `ToolResult { output, .. }` | String | Push sebagai tool message |
| `Usage { tokens_in, tokens_out }` | u64, u64 | Update `usage` stats |
| `Error(msg)` | String | Toast error |
| `Compacted(msgs)` | `Vec<ChatMessage>` | Update `session_runtime.messages` |
| `SystemNote { kind, message }` | String | Push ke transcript |
| `Done` | — | Set `turn_in_flight_flag = false` |