manual_slop/docs/reports/EXCEPTION_HANDLING_AUDIT_20260616.md

Exception Handling Audit Report (Data-Oriented Convention Compliance)

Date: 2026-06-16 Track ID: exception_handling_audit_20260616 Status: COMPLETED (5/5 phases) Reviewer: User (handoff for next-track decision)

---

0. TL;DR

A static analyzer (scripts/audit_exception_handling.py) classified every try/except/finally/raise site in the codebase (65 files, 348 sites) against the data-oriented error handling convention established by data_oriented_error_handling_20260606 (shipped 2026-06-12).

Headline	Count
Total sites	348
Compliant sites	80 (23%)
Suspicious sites	25 (7%)
Violation sites	211 (61%)
Unclear (manual review)	32 (9%)

Key finding: the convention is partially applied (3 of 65 src/ files are refactored: mcp_client.py, ai_client.py, rag_engine.py). The remaining ~10 files in src/ are in the migration-target state.

File Group	Sites	Violations	Note
Baseline (3 refactored files)	112	77	Convention reference; even these have remaining except Exception + log patterns that should be Result-converted
Migration target (62 other files)	236	134	The work for future refactor tracks

What the user decides: which migration-target file is the next refactor track? The top 5 candidates by violation count are: gui_2.py (37), app_controller.py (35), session_logger.py (8), warmup.py (6), theme_models.py (6).

Important: the "violation count" is NOT a bug count. These are migration-target sites, not bugs. The codebase works correctly today (1288 + 4 + 0 test pass). The audit identifies which files would benefit from future refactor tracks; the user decides what to migrate.

---

1. Methodology

1.1 The 10 Classification Categories

The audit classifies each site into one of 10 categories (5 compliant, 3 violation, 1 suspicious, 1 unclear):

Category	Convention status	When
BOUNDARY_SDK	Compliant	Wraps a third-party SDK call
BOUNDARY_IO	Compliant	Wraps stdlib I/O that can raise
BOUNDARY_CONVERSION	Compliant	Catches and converts to ErrorInfo in a Result
BOUNDARY_FASTAPI	Compliant	FastAPI HTTPException in _api_* handler
INTERNAL_SILENT_SWALLOW	Violation	except ...: pass or just logs
INTERNAL_BROAD_CATCH	Violation	except Exception without ErrorInfo conversion, in non-*_result code
INTERNAL_OPTIONAL_RETURN	Violation	try/except + return None/Optional[T]
INTERNAL_RETHROW	Suspicious	try/except + raise (without ErrorInfo conversion)
INTERNAL_PROGRAMMER_RAISE	Compliant	raise for impossible state / precondition (__init__, assert, ValueError)
INTERNAL_COMPLIANT	Compliant	try/finally (no except) — canonical cleanup
UNCLEAR	Review needed	Can't determine automatically

1.2 The Baseline vs Migration-Target Split

The 3 fully-refactored files (per the data_oriented_error_handling_20260606 track) are the baseline — the convention reference. The other ~62 files are the migration target. The audit reports both separately so the user can distinguish "the convention has gaps even in the refactored files" from "the convention has not been applied to the unrefactored files".

1.3 The Script's Classification Logic

The script uses Python's ast module (not regex) to walk each source file's AST and classify each try/except/finally/raise node. The classification considers:

1. The exception type (third-party SDK exception, stdlib I/O exception, FastAPI exception, programmer-error exception, etc.)
2. The enclosing function name (_api_* for FastAPI, *_result for Result-returning, __init__ for constructors)
3. The return type annotation of the enclosing function (Result[T] vs Optional[T] vs plain T)
4. What the catch site does with the exception (ErrorInfo conversion, re-raise, return None, silent swallow, etc.)
5. What the try body calls (third-party SDK module vs internal method)

The script outputs a 1-line hint per site suggesting what the fix could look like (e.g., "return Result(data=NIL_T, errors=[...])").

1.4 What the Script Does NOT Do

• Does NOT execute the code (it's a static analyzer; no behavior change).
• Does NOT modify any files.
• Does NOT provide specific refactor patches (the "hint" is a 1-line suggestion; the implementer of the next refactor track writes the actual code).
• Does NOT verify that refactored code works (no test execution; the audit report is the deliverable).

---

2. The 3 Refactored Baseline Files (Convention Reference)

These 3 files are the convention reference. Sites in these files are labeled in_refactored_baseline: true in the JSON output.

2.1 src/mcp_client.py (refactored 2026-06-12)

• Total sites: 53
• Violations: 44 (40 INTERNAL_BROAD_CATCH + 4 INTERNAL_SILENT_SWALLOW)
• Compliant sites: 5
• Unclear: 4

Note: the spec for the parent track chose "Path C" (additive *_result variants alongside the existing (p, err) tuple API). The 30+ tool-function refactor + assertion chain removal is deferred. The 44 violations are mostly the remaining (p, err) + except Exception + log patterns in the 30+ tool functions that haven't been refactored yet.

2.2 src/ai_client.py (refactored 2026-06-12)

• Total sites: 46
• Violations: 27 (18 INTERNAL_BROAD_CATCH + 9 INTERNAL_SILENT_SWALLOW)
• Compliant sites: 8
• Suspicious sites: 9
• Unclear: 2

Note: the ProviderError exception class was REMOVED; all 8 _send_<vendor>_result() functions return Result[str]. The 27 violations are mostly the broad-catches in the SDK-exception-classification helpers (which catch anthropic.APIError, google.api_core.exceptions.*, etc., but don't convert to ErrorInfo at the catch site — they log and re-raise).

2.3 src/rag_engine.py (refactored 2026-06-12)

• Total sites: 13
• Violations: 6 (5 INTERNAL_BROAD_CATCH + 1 INTERNAL_SILENT_SWALLOW)
• Compliant sites: 1
• Suspicious sites: 8

Note: _init_vector_store_result and _validate_collection_dim_result return Result[None] with ErrorInfo conversion. The 6 violations are the remaining broad-catches in non-*_result methods (add_documents, etc.).

2.4 The 77 Baseline Violations Are NOT Bugs

The 77 violations in the 3 refactored files are migration-target sites in files that are otherwise convention-compliant. The refactor was incomplete (per the parent's Path C decision for mcp_client and the incremental migration strategy). The user can decide to do follow-up refactors to close these 77 sites, or to accept them as "good enough for the convention reference" and focus on the larger unrefactored files.

---

3. Per-File Violation Counts (Top 15 Migration-Target Files)

Rank	File	Total	Violations	Suspicious	Unclear	Compliant	Note
1	src/gui_2.py (260KB)	54	37	2	13	2	Largest file; 25 INTERNAL_BROAD_CATCH + 12 INTERNAL_SILENT_SWALLOW
2	src/app_controller.py (166KB)	56	35	3	2	16	13 of 35 are FastAPI boundary (compliant); 22 are migration-target
3	src/session_logger.py	8	8	0	0	0	All silent-swallow + broad-catch
4	src/warmup.py	7	6	1	0	0	Startup-time broad-catches
5	src/theme_models.py	10	6	0	2	2	Mostly re-raise
6	src/api_hooks.py	5	5	0	0	0	FastAPI HookServer; many broad-catches
7	src/project_manager.py	5	5	0	0	0	3 silent-swallow + 2 broad-catch
8-15	(10 other files, 0-3 violations each)	91	32	6	14	39	Mixed; small files

Total migration-target sites: 236 Total migration-target violations: 134 Total migration-target compliant: 70 (mostly INTERNAL_PROGRAMMER_RAISE in __init__ + try/finally cleanup patterns + a few BOUNDARY_SDK from chromadb/requests imports)

---

4. Per-Category Breakdown

4.1 Violations (211 sites, 61% of total)

Category	Count	Typical pattern	Fix hint
INTERNAL_BROAD_CATCH	147	try: ...; except Exception: log(...)	Narrow the exception type OR convert to ErrorInfo in a Result
INTERNAL_SILENT_SWALLOW	61	try: ...; except SomeError: pass	Let it propagate OR return Result(data=NIL_T, errors=[...]) OR document with assert
INTERNAL_OPTIONAL_RETURN	3	try: ...; except: return None	Replace with Result[T] returning Result(data=NIL_T, errors=[...])

4.2 Compliant (80 sites, 23% of total)

Category	Count	Typical pattern
INTERNAL_PROGRAMMER_RAISE	25	raise ValueError in __init__; assert for impossible states
BOUNDARY_SDK	19	except anthropic.APIError; except google.api_core.exceptions.*
INTERNAL_COMPLIANT	16	try/finally cleanup pattern
BOUNDARY_FASTAPI	12	raise HTTPException in _api_* handler
BOUNDARY_CONVERSION	8	except Exception as e: return Result(data=..., errors=[ErrorInfo(...)])

4.3 Suspicious (25 sites, 7% of total)

Category	Count	Typical pattern	Fix hint
INTERNAL_RETHROW	25	try: ...; except: log(); raise (no conversion)	See "Re-Raise Patterns" in the styleguide; 3 legitimate patterns + 1 suspicious

4.4 Unclear (32 sites, 9% of total)

Category	Count	Typical pattern
UNCLEAR	32	Can't determine automatically; needs human review

The 32 UNCLEAR sites are mostly in src/gui_2.py (13) and the smaller files (theme_models, project_manager, etc.). They have ambiguous exception-handling patterns where the script's heuristics don't definitively classify. The --verbose flag shows each one inline.

---

5. The 5 Doc Gaps Closed (this track's secondary deliverable)

The audit revealed 5 gaps in the existing documentation of the convention. This track closed all 5.

5.1 G1: FastAPI HTTPException in _api_* handlers (CLOSED)

Gap: the styleguide said "exceptions are reserved for the SDK boundary" but didn't address the FastAPI framework boundary. The audit found 13 sites in src/app_controller.py that use FastAPI's idiomatic HTTPException pattern.

Fix: added a new "Boundary Types" section to the styleguide with 3 categories of legitimate boundaries (third-party SDK, stdlib I/O, framework). The framework category explicitly covers FastAPI. The new docs/guide_app_controller.md "Exception Handling" section explains the 13 sites in detail.

5.2 G2: The "broad except Exception" rule (CLOSED)

Gap: the styleguide's anti-pattern #6 says "DON'T catch except Exception and silently swallow." But except Exception + ErrorInfo conversion is the canonical SDK boundary pattern (per the parent's spec §3.3). The rule was ambiguous.

Fix: added a new "The Broad-Except Distinction" section to the styleguide. The section provides a decision table showing when except Exception is compliant (conversion to ErrorInfo) vs when it's a violation (swallow / log-only). The new BOUNDARY_CONVERSION and INTERNAL_BROAD_CATCH categories in the audit implement this rule.

5.3 G3: The "constructors can raise" rule (CLOSED)

Gap: the styleguide §"When to Use This Convention" mentions "Constructors (__init__) that fail with programmer errors (use assert or raise for these)" but the wording is brief. The audit found multiple legitimate ValueError raises in __init__ and assert sites.

Fix: added a new "Constructors Can Raise" section to the styleguide with 2 code examples (the ValueError pattern + the assert pattern) and a list of 9 recognized programmer-error exception types. The new INTERNAL_PROGRAMMER_RAISE category in the audit implements this rule.

5.4 G4: The "re-raise" pattern (CLOSED)

Gap: the styleguide's anti-patterns say "DON'T raise a custom exception class for runtime failures" but re-raising is a separate concern that needs its own rule. The audit found 25 try/except + raise sites in src/.

Fix: added a new "Re-Raise Patterns" section to the styleguide with 3 legitimate re-raise patterns (convert, log, cleanup) + 1 suspicious pattern (catch + re-raise the same exception). The new INTERNAL_RETHROW category in the audit implements this rule.

5.5 G5: The audit script reference (CLOSED)

Gap: the new scripts/audit_exception_handling.py wasn't referenced from any of the convention's documentation.

Fix: added a new "Audit Script" section to the styleguide. The section documents the script's usage, the classification categories, the "delete to turn off" pattern (per feature_flags.md), and the output structure. Also added a cross-reference from conductor/product-guidelines.md "Data-Oriented Error Handling" section.

---

6. The Migration Target (the work for future refactor tracks)

The 211 violations are distributed across 42 files. The user decides which file(s) to migrate next. The top 3 candidates by violation count:

6.1 src/gui_2.py (37 violations, 260KB)

The largest file in the codebase. The 37 violations are mostly the INTERNAL_BROAD_CATCH (25) + INTERNAL_SILENT_SWALLOW (12) patterns. 13 sites are UNCLEAR (manual review needed).

Migration scope estimate: 2-3 days Tier 2 work to migrate the file to the convention. The work would be: convert Optional[T] return types to Result[T]; convert except Exception + log/print to except Exception + return Result(...); add tests for the new Result-based API.

Risk: the file is the GUI rendering layer; changes here affect every render frame. The migration should be done incrementally with the hot-reload mechanism (Ctrl+Alt+R) so the user can verify each change visually.

6.2 src/app_controller.py (35 violations + 16 compliant, 166KB)

The headless orchestrator. The 35 violations are 28 INTERNAL_BROAD_CATCH + 6 INTERNAL_SILENT_SWALLOW + 1 INTERNAL_OPTIONAL_RETURN. The 16 compliant sites are 13 FastAPI boundary + 3 INTERNAL_PROGRAMMER_RAISE.

Migration scope estimate: 2-3 days Tier 2 work. The 13 FastAPI boundary sites stay as-is (they're the framework contract). The 22 migration-target sites are the work.

Risk: the controller is the orchestrator and touches every subsystem. Changes here require careful coordination with the _predefined_callbacks and _gettable_fields registries (per the Hook API). The migration should be done in 5-file commits (the parent track's pattern).

6.3 src/session_logger.py (8 violations)

A small file (16KB). The 8 violations are 4 INTERNAL_BROAD_CATCH + 4 INTERNAL_SILENT_SWALLOW.

Migration scope estimate: 0.5 day Tier 2 work. The file is small and the migration is straightforward.

Risk: low. The file is self-contained.

---

7. Followup Recommendations (for the user's next-track decision)

The user has 4 options for what to do next:

#	Option	Scope	Estimated effort	Rationale
1	Do the planned send_result → send mass rename (manual refactor)	Mechanical find-replace of the function name	1-2 hours	User's stated intent. Mechanical, low-risk. Doesn't change test pass count.
2	Migrate app_controller.py to the convention	22 migration-target sites	2-3 days Tier 2	The highest-priority migration per the doeh spec §12.2. The 13 FastAPI boundary sites stay.
3	Migrate gui_2.py to the convention	37 migration-target sites	2-3 days Tier 2	The largest file; would close the biggest single chunk.
4	Migrate session_logger.py + warmup.py + theme_models.py together	20 migration-target sites in 3 small files	0.5-1 day Tier 2	Quick wins; clears 3 files at once.

The recommended order is 1 → 2 → 3 → 4 (do the mechanical rename first, then the orchestrator migration, then the GUI, then the small files). The user decides.

---

8. Verification Artifacts

• tests/artifacts/exception_handling_audit_final.log — the human-readable audit output (103 lines, 7.4KB)
• tests/artifacts/exception_handling_audit_final.json — the JSON output (43.7KB, machine-readable)
• scripts/audit_exception_handling.py — the static analyzer (792 lines)
• conductor/code_styleguides/error_handling.md — updated with 5 new sections
• docs/guide_app_controller.md — updated with the FastAPI boundary section
• conductor/product-guidelines.md — updated with the audit script cross-reference
• docs/reports/EXCEPTION_HANDLING_AUDIT_20260616.md — this report

---

9. Test Pass Count (unchanged from rag_test_failures_20260615)

This track is informational (no code change). The test pass count is 1288 + 4 + 0 (unchanged from the previous track's baseline).