Quality cleanup refactoring

Made-with: Cursor

_docs/04_refactoring/01-quality-cleanup/analysis/research_findings.md

@@ -0,0 +1,61 @@
+# Research Findings
+
+## Current State Analysis
+
+### Strengths
+- Small codebase (785 LOC) — easy to reason about
+- Clear component boundaries (Core Models → Security → Resource Mgmt → HTTP API)
+- Cython compilation achieves IP protection goal
+- Binary-split scheme is clever security design
+- E2e test suite now provides 100% endpoint coverage (18 tests, all passing)
+
+### Weaknesses
+- Thread safety gaps in the singleton and global state patterns
+- Manual cryptographic operations where library functions exist
+- Dead code accumulated from earlier iterations
+- Hardcoded configuration values
+
+## Change-Specific Analysis
+
+### C01/C02: Thread Safety (main.py)
+
+**Current**: Bare global variable + `if None` check for ApiClient singleton. Module-level globals for unlock state.
+
+**Recommended approach**: Double-checked locking with `threading.Lock` for the singleton. Encapsulate unlock state in a class with lock-guarded accessors. These are standard Python concurrency patterns — no library changes needed.
+
+**Alternative considered**: Using `functools.lru_cache` for singleton — rejected because it doesn't provide thread safety guarantees for the initialization side-effects (CDN config download).
+
+### C03/C04: PKCS7 Padding (security.pyx, binary_split.py)
+
+**Current**: Manual last-byte inspection without full padding validation.
+
+**Recommended approach**: Use `cryptography.hazmat.primitives.padding.PKCS7(128).unpadder()` — already imported in `security.pyx`. For `binary_split.py`, integrate the library's unpadder into the streaming decryption instead of post-hoc file truncation.
+
+**Risk**: If any existing encrypted data was produced with non-standard padding, the library unpadder will raise `ValueError` instead of silently passing. This is correct behavior — it surfaces corruption that was previously hidden.
+
+### C05: Log Path (constants.pyx)
+
+**Current**: Hardcoded `"Logs/log_loader_{time:YYYYMMDD}.txt"`.
+
+**Recommended approach**: `os.environ.get("LOG_DIR", "Logs")` — minimal change, no new dependencies.
+
+### C06: Error Handling (main.py)
+
+**Current**: `except OSError: pass` — violates project rules.
+
+**Recommended approach**: Import `constants` and call `constants.logerror()`. One-line fix.
+
+**Note**: `constants` is a Cython module — `main.py` would need to import the compiled `.so`. This works because `main.py` already imports other Cython modules indirectly via `api_client`. However, `main.py` currently only imports `unlock_state` (pure Python). A simpler approach is using `loguru.logger.warning()` directly since loguru is already configured by the time `main.py` runs.
+
+### C07/C08: Dead Code Removal
+
+**Approach**: Straight deletion. Git history preserves everything. No behavioral risk.
+
+## Prioritized Recommendations
+
+| Priority | Changes | Rationale |
+|----------|---------|-----------|
+| 1 (critical fix) | C03, C04 | Correctness — silent data corruption on invalid padding |
+| 2 (safety) | C01, C02 | Thread safety under concurrent requests |
+| 3 (cleanup) | C07, C08 | Reduce cognitive load, prevent drift |
+| 4 (minor) | C05, C06 | Configurability and error visibility |