looper/evaluation.md

Client Code Evaluation

Summary Table

Category	Rating	Remarks
Mocked / Left Undone	⚠️ Incomplete	Most features are stubs. Only four FIFO commands are sent: record <col>, scene_next, stop, and ? toggles help. Visual mode, yank/paste, fuzzy search, zoom, MIDI grid, rack view, transport controls, and all other keybindings are placeholders. The TUI does not display engine state – all cells show a static number with a single color.
Potential Segfaults	✅ Low Risk	No unsafe pointer dereferences. All array indices are bounded by modulo. send_command opens with O_NONBLOCK and returns -1 on failure – callers (except test_client.c) ignore it, but no crash occurs. yank_buffer.clip_indices is never allocated; free(NULL) is safe. No null pointer accesses in ncurses calls.
Memory Safety	✅ Good	Only stack‑allocated data. The sole dynamic allocation (yank_buffer.clip_indices) is never allocated, so the free in tui_cleanup is harmless. No leaks, no use‑after‑free.
Thread Safety / Race	✅ None	The entire TUI runs on the main thread. No concurrency, no shared state. send_command is called synchronously. No race conditions.
Performance	✅ Acceptable	Main loop blocks on getch(). Each command opens, writes, and closes a FIFO – system call overhead, but acceptable at human interaction rate (~dozen commands/s). No CPU‑intensive work. draw_grid redraws the entire screen; with 8×8 grid it is negligible.
Architectural Soundness	✅ Reasonable	Clean separation: TUI communicates only via FIFO, no engine linkage. send_command is testable (unit test passes). The architecture supports future extension (add new keybindings → call send_command). However, the current implementation sends commands without any feedback or validation; the user receives no visual confirmation that the engine acted.

Detailed Remarks

1. Mocked / Left Undone

• Clip state display: All cells use COLOR_EMPTY (white) regardless of actual engine state. state_to_color() returns a fixed value.
• Visual mode: Declared (MODE_VISUAL, MODE_MOVE) but never triggered. marks array is initialized but never written or read.
• Yank buffer: yank_buffer.clip_indices is never allocated; yank_buffer.count is always 0. Paste (p) not implemented.
• Fuzzy search: FuzzySearch struct exists with all fields, but never used. No file listing or Carla integration.
• Rack view: Not implemented; key \t is not handled.
• Many engine commands missing: bind, unbind, add_channel, remove_channel, add_midi, scene_prev, toggle_play, record_stop, MIDI note events, etc., are not mapped.
• Transport controls: No play/pause toggle – engine has no corresponding FIFO command yet.
• Help text: Only a single line; many described keys are not actually handled.
• Mouse: Not handled.
• Colors: Only COLOR_EMPTY and COLOR_SELECTED are used dynamically; colours for looping, recording, stopped states are initialized but never applied.

The code is a minimal stub – exactly as defined in PLAN.md. This is acceptable for the first phase, but the client is far from usable as a real looper UI.

2. Potential Segfaults

• send_command returns -1 on failure; callers in the main loop (cases t, s, d) ignore the return value. No crash.
• draw_cell uses fixed coordinates; no off‑screen access. Grid is 8×8, coordinates are bounded by modulo.
• send_command accesses getenv("LOOPER_CMD_FIFO") – returns NULL if unset; code then uses hardcoded /tmp/looper_cmd. Safe.
• Open with O_NONBLOCK avoids blocking hang.
• write() return value is checked for short writes only when appending newline.
• No pointer arithmetic or unsafe casts.

3. Memory Safety

• The only dynamic allocation is yank_buffer.clip_indices – it is never assigned a value, remains NULL. tui_cleanup calls free(NULL) – well‑defined.
• All other data is static or stack‑allocated.
• No realloc or custom allocators.
• No memory leaks.

4. Thread Safety / Race Conditions

• Single‑threaded. No threads are spawned.
• send_command is synchronous and blocking; no concurrent access to the file.
• No atomics, locks, or shared mutable state.

5. Performance

• Main loop blocks on getch() – CPU idle.
• Each FIFO command incurs one open(), write(), close() system call. With a real FIFO, open() with O_NONBLOCK returns immediately or fails. This is acceptable at UI speeds.
• draw_grid does a clear() and refreshes the entire screen; for 64 cells it is fast enough (sub‑millisecond).
• No audio processing or heavy computation.

6. Architectural Soundness

• Separation: The client has zero dependency on engine source code; it communicates only via FIFO.
• Testability: send_command is exposed and can be tested independently (existing unit test works).
• Extensibility: Adding a new command is trivial – add a case and call send_command with a formatted string. The plan already defines the mapping.
• Weakness: No feedback path from the engine; the user has no visual confirmation that their action took effect. A future read‑back FIFO or shared memory would be required for a production UI.
• Placeholder code: Many structures and functions (FuzzySearch, marks, visual mode) are dead code – they increase compilation time but do not affect runtime. They can be removed when the corresponding features are implemented properly.

Overall Verdict

The client code is minimal, safe, and architecturally sound for its intended first‑phase purpose.

• It compiles without errors and passes its unit test.
• No segfaults, memory leaks, or race conditions exist.
• Performance is acceptable for interactive use.
• The architecture cleanly separates UI from engine and supports incremental feature addition.

Missing features are deliberate stubs as per PLAN.md. The client is a functional skeleton that can be extended once the engine exposes more FIFO commands and a feedback channel.