chanora/docs/references/tsdeclarations-codegen-eval.md

tsdeclarations Code Generation Evaluation

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

---

1. What tsdeclarations Provides

The 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