Private
Public Access
0
0

docs: add Sentinel type contract note to 3 defer-not-catch sections

This commit is contained in:
2026-06-05 20:31:38 -04:00
parent 0e299140ca
commit 1488e71568
3 changed files with 6 additions and 0 deletions
+2
View File
@@ -409,6 +409,8 @@ The fix is **defer-not-catch**: track a one-shot "ready" flag in instance state;
When designing any method that calls into `imgui.*` (or similar native libs), ask: "Can this be called before ImGui is fully initialized?" If yes, add a defer-not-catch guard.
**Sentinel type contract.** When implementing a defer-not-catch guard, the early-return sentinel value must match the type contract of the downstream consumer. For `WorkspaceProfile.ini_content: str` (in this codebase), the sentinel must be `""` (str), not `b""` (bytes) — `tomli_w` rejects bytes (`TypeError: Object of type 'bytes' is not TOML serializable`), and `imgui.load_ini_settings_from_memory(ini_data: str, ...)` also expects `str`. A previous version of this fix used `b""` and silently broke the save flow via a `TypeError` raised by `tomli_w.dump`; tests passed unit-test-wise but failed in the live_gui save+load round-trip. The fix was a 1-character change (`b""` → `""`). The regression test in `tests/test_workspace_profile_serialization.py` encodes this contract.
### Test Failure Bisect Anchors (Theme Track)
When debugging test failures introduced by a theming/visual change, use the following bisect anchors: