# tsdeclarations Code Generation Evaluation

**TODO-068** — Evaluate Messages.toml, Book.toml, Enums.toml for code generation feasibility.

---

## 1. What tsdeclarations Provides

The [ReSpeak/tsdeclarations](https://github.com/ReSpeak/tsdeclarations) repository contains machine-readable protocol data files used for code generation across the ReSpeak ecosystem:

| File | Purpose | Format |
|------|---------|--------|
| `Messages.toml` | All TS3 client↔server commands and their parameters | TOML structs with typed fields |
| `Book.toml` | State-tracking structures for server entities (Client, Channel, Server, ServerGroup, etc.) | TOML structs with typed fields |
| `Enums.toml` | Protocol enums (Codec, PermissionType, Reason, ChannelType, LicenseType, etc.) | TOML enum definitions |
| `MessagesToBook.toml` | Mappings from incoming commands to Book struct updates | TOML mapping rules |
| `BookToMessages.toml` | Functions to generate outgoing commands from Book state | TOML generation rules |
| `Errors.csv` | All TS3 error codes (hex, name, description) | CSV |
| `Permissions.csv` | All TS3 permission IDs (name, description, numeric ID) | CSV |
| `Versions.csv` | Known client version hashes (1536 entries) | CSV |
| `Badges.csv` | Known badge GUIDs and metadata | CSV |

### How ReSpeak Uses Them

The `tsclientlib` workspace consumes these via:

- **`tsproto-structs`** — build-time code generation from TOML files into Rust structs
- **`tsproto-types`** — basic TS3 types (error codes, versions, UIDs)
- **`ts-bookkeeping`** — state tracking that maps incoming messages to Book struct updates
- **`tsproto-packets`** — command parsing/serialization

Chanora already depends on `tsproto-structs`, `tsproto-types`, and `ts-bookkeeping` as git dependencies (via `chanora_protocol`).

---

## 2. Current Chanora Usage

| Component | Source | Status |
|-----------|--------|--------|
| `tsproto-types` | Git dependency (patched fork for P-256 coordinate padding) | Active |
| `tsproto-structs` | Git dependency (rev 04aa2491) | Active |
| `ts_bookkeeping` | Used in `chanora_protocol/src/adapter.rs` for event projection | Active |
| Error codes | Referenced from `Errors.csv` via `tsproto-types` | Active |
| Version hashes | Baked into `adapter.rs` from `Versions.csv` | Active |
| Permissions | **Not used** — no TS3 permission ID mapping exists in Chanora |
| `Messages.toml` | **Not directly used** — Chanora uses `ts_bookkeeping` which consumes it internally |
| `Book.toml` | **Not directly used** — consumed by `ts_bookkeeping` internally |
| `Enums.toml` | **Not directly used** — consumed by `tsproto-structs` internally |

---

## 3. Feasibility Assessment

### 3.1 Automating Protocol Struct Generation

**Verdict: Already happening indirectly via tsproto-structs/ts_bookkeeping.**

Chanora already benefits from the tsdeclarations code generation pipeline through its dependency on `tsproto-structs` and `ts_bookkeeping`. The TOML files are consumed at build time by these upstream crates, producing:

- Typed command structs (`c2s::Clientinit`, `s2c::Initserver`, etc.)
- Event mapping logic (`Event`, `PropertyId`, `PropertyValue`)
- Book state structures

Direct consumption of `Messages.toml`/`Book.toml` to generate *Chanora-specific* structs would be **redundant** with the existing `ts_bookkeeping` dependency.

### 3.2 Generating Chanora-Specific DTOs from Book.toml

**Verdict: Moderate value, moderate effort.**

The `Book.toml` defines the canonical shape of tracked entities (Client, Channel, Server, ServerGroup, ChannelGroup). Chanora currently has its own DTO types:

- `BridgeClient` / `BridgeChannel` / `BridgeSnapshot` (in `chanora_bridge/src/api.rs`)
- `ClientProfile` / `ServerSnapshot` (in `chanora_core`)

A code-gen step could auto-generate these DTOs from `Book.toml`, ensuring field parity with the protocol. However:

- Chanora's DTOs intentionally omit many protocol fields (privacy, simplicity)
- The mapping from Book fields to bridge DTOs involves business logic (e.g., `PermissionHints` gating)
- Manual DTOs are easier to evolve independently

**Recommendation:** Keep manual DTOs. Use `Book.toml` as a *reference* when adding new fields, not as a code-gen source.

### 3.3 Generating Event Types from Messages.toml

**Verdict: Low value for Chanora.**

`ts_bookkeeping` already handles the command→event mapping. Chanora's `SessionEvent` enum is a higher-level abstraction that doesn't map 1:1 to protocol commands. Auto-generating it from `Messages.toml` would require a complex mapping layer that defeats the purpose.

### 3.4 Error Code and Permission ID Generation

**Verdict: High value, low effort.**

The CSV files (`Errors.csv`, `Permissions.csv`) are simple, stable, and directly useful:

- **Errors**: Chanora already references `Errors.csv` names but hardcodes hex values. A build step could generate a `const` table.
- **Permissions**: No permission ID mapping exists yet (TODO-069). `Permissions.csv` is the canonical source.

### 3.5 Version Hash Generation

**Verdict: Already done manually; automation possible but low priority.**

Version hashes from `Versions.csv` are baked into `adapter.rs` at vendor time. A build step could auto-update them, but the list changes infrequently.

---

## 4. Recommended Approach

| Priority | Action | Effort | Value |
|----------|--------|--------|-------|
| P1 | Use `Permissions.csv` to generate a Rust permission ID constants module (see TODO-069) | 1–2 days | High |
| P2 | Use `Errors.csv` to generate a typed error code enum with `From<u16>` | 0.5 days | Medium |
| P3 | Add a CI check that diffs `tsproto-structs`/`ts_bookkeeping` against upstream tsdeclarations HEAD | 0.5 days | Medium |
| P4 | Keep `Book.toml`/`Messages.toml` as reference documentation only | 0 days | — |

### What NOT to Do

- **Do not** fork or vendor the TOML files into Chanora's build pipeline
- **Do not** auto-generate Chanora's bridge DTOs from `Book.toml`
- **Do not** auto-generate `SessionEvent` from `Messages.toml`
- **Do not** maintain a separate TOML parser — let upstream crates handle this

---

## 5. Effort Estimate

| Task | Estimate |
|------|----------|
| Permission ID constants from `Permissions.csv` | 1–2 days |
| Error code enum from `Errors.csv` | 0.5 days |
| CI upstream diff check | 0.5 days |
| **Total** | **2–3 days** |

---

## 6. Dependencies and Risks

- **Upstream stability**: `tsdeclarations` is MIT/Apache-2.0 licensed, active (94 commits), and used by `tsclientlib`. Low risk of abandonment.
- **TS5 compatibility**: The files may need updates when TS5 protocol stabilizes (TODO-058 monitors this).
- **Patched fork**: Chanora uses a patched `tsproto-types` fork for P-256 coordinate padding. Any code-gen from upstream must account for this.

---

*Created: 2026-06-11 for TODO-068*