Quality cleanup refactoring

Made-with: Cursor

_docs/04_refactoring/01-quality-cleanup/discovery/logical_flow_analysis.md

@@ -0,0 +1,44 @@
+# Logical Flow Analysis
+
+Traced all 6 documented flows (F1-F6) through actual code. Findings below.
+
+## F1 Authentication — No contradictions
+
+Flow matches documentation. `set_credentials_from_dict` → `set_credentials` → `load_bytes(CDN_CONFIG)` → triggers `login()` internally → downloads cdn.yaml → inits CDNManager. Naming (`set_credentials_from_dict`) understates what the method does, but behavior is correct.
+
+## F2 Resource Download — No contradictions
+
+`load_big_small_resource` correctly: downloads small part (API), checks local big part, falls back to CDN on decrypt failure. The `folder` parameter doubles as S3 bucket name and local directory — works by convention.
+
+## F3 Resource Upload — No contradictions
+
+`upload_big_small_resource` encrypts, splits at min(3KB, 30%), uploads big to CDN + local, small to API. Flow matches docs.
+
+## F4 Docker Unlock — Minor inefficiency
+
+`_run_unlock` calls `set_credentials_from_dict(email, password)` then `client.login()`. If the client is fresh, `set_credentials_from_dict` already triggers `login()` internally (through the CDN config download chain), making the explicit `login()` call redundant. Not a bug — just a wasted HTTP round-trip.
+
+## F5 Unlock Status — No contradictions
+
+Reads `unlock_state` and `unlock_error` under `unlock_lock`. Correct.
+
+## F6 Health/Status — No contradictions
+
+`/health` returns static response. `/status` reads `client.token`. Correct.
+
+## Strategic Note: Binary-Split Security Model May Be Obsolete
+
+The binary-split resource scheme (small part on API + big part on CDN) and the loader's key-fragment-based Docker unlock were designed for a specific threat model: distributing AI models to **end-user laptops** where the device is untrusted. The loader shipped only 99% of the model in the installer; the remaining 1% (first 3KB) was downloaded at runtime to prevent extraction.
+
+The software distribution model has since shifted to **SaaS** — services run on web servers or **Jetson Orin Nano** edge devices where the entire system can be secured via **TPM** (Trusted Platform Module). This makes the binary-split mechanism potentially unnecessary overhead.
+
+**Recommended investigation**: Evaluate whether TPM-based security on Jetson Orin Nano can replace the binary-split scheme entirely, simplifying the loader to a standard authenticated resource downloader. This is out of scope for the current refactoring run but should be tracked as a future architecture decision.
+
+## Additional Dead Code Found
+
+`constants.pxd` declares 3 variables never defined in `constants.pyx`:
+- `QUEUE_MAXSIZE` (line 3)
+- `COMMANDS_QUEUE` (line 4)
+- `ANNOTATIONS_QUEUE` (line 5)
+
+These are orphan forward declarations — no definition exists, and nothing references them. Added to Issue 6.