szn

Bug 507 — “No global state” claim contradicted by eleven mutable globals

507. Documented design principle does not match the implementation

Severity: LOW (architecture)
Status: ✅ FIXED
Files: AGENTS.md:59, docs/architecture.md:153, src/char_width.zig:30, src/thai.zig:460, src/log.zig:36

Problem

Two documents state the principle as absolute:

<!-- AGENTS.md:59 -->
4. **No global state.** Pass context explicitly. Use build-time dependency
   injection for testing.
<!-- docs/architecture.md:153 -->
- No global state — context passed explicitly through `Server`/`Screen`/`Pane`.

rg -n '^var ' src/ returns eleven mutable module-level globals:

Global File Assessment
override_count, overrides char_width.zig:30-31 genuine design debt — causes bug #506
variation_selector_always_wide char_width.zig:47 genuine design debt — causes bug #506
libthai_instance, libthai_state thai.zig:460-461 acceptable; justified in the getLibThai docstring (bug #504) and confined to lazy dylib init
log_fd log.zig:36 genuine design debt
log_fd_failed, log_enabled log.zig:37-38 genuine design debt
runtime_log_level log.zig:112 genuine design debt
sigchldFlag server/server.zig:12 required — async-signal-safe handler target
sigwinchFlag, sighupFlag main.zig:36,39 required — async-signal-safe handler targets

The signal-handler globals cannot be threaded through context: a POSIX signal handler may only touch volatile sig_atomic_t objects, so these are a correct and unavoidable exception that simply is not documented as one.

The remaining eight are ordinary configuration and cache state that could be reached through an explicit context parameter. The char_width group is not cosmetic — it is the mechanism behind bug #506, where a session-scoped option mutates a process-global table.

An unqualified “no global state” claim in the project’s own agent instructions is worse than no claim at all, because an agent or reviewer reading AGENTS.md will assume the invariant holds and will not look for exceptions.

Proposed Fix

Two options, in order of effort:

  1. Qualify the claim (minutes). Amend both documents to name the exceptions, e.g. “No global state, with three documented exceptions: async-signal handler flags (sigchldFlag, sigwinchFlag, sighupFlag), the lazily-initialised libthai handle (bug #504), and the logger’s fd and level state. Terminal-width and codepoint-width tables are the remaining candidates for removal — see bug #506.”
  2. Remove the removable globals (days). Fold log_fd / log_enabled / runtime_log_level into a Logger struct passed by pointer, and resolve char_width’s tables per bug #506. This makes the original claim true.

Option 1 should land regardless, since option 2 depends on the scope decision in bug #506.

Resolution

Fixed by qualifying the claim in both places rather than removing the globals, which depends on the scope decision in bug #506.

The claim is now true as written: it is a default to defend, with the exceptions enumerated, rather than an absolute that a reviewer would not think to check.