Skip to content

Phase 1: Registry[T] + exception hierarchy + core utilities #329

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
andyne13 merged 9 commits into from
Apr 21, 2026
Merged

Phase 1: Registry[T] + exception hierarchy + core utilities #329

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
81be787
core: add generic Registry[T] pattern
andyne13 Apr 21, 2026
237d9fc
core: add unified exception hierarchy
andyne13 Apr 21, 2026
e32af99
shim: re-export exceptions from core for backward compatibility
andyne13 Apr 21, 2026
eb6bbfe
cleanup: remove core/catalog/, update decision log
andyne13 Apr 21, 2026
0f530da
core: add text sanitization utilities
andyne13 Apr 21, 2026
db4d632
core: add filename sanitization utilities
andyne13 Apr 21, 2026
4197df4
core: add external resource error detection
andyne13 Apr 21, 2026
85ce612
style: fix ruff lint errors in core/utils
andyne13 Apr 21, 2026
97b5b9e
style: apply ruff formatting to core/utils
andyne13 Apr 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions REFACTORING_DECISION_LOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,23 @@ match reality, then record the reasoning here.

## Template for future entries

## Phase 1 — Registry + Exceptions (2026-04-21)

**1. Exceptions keep HTTP status_code on the class (OpenRAG style), not in
a separate error handler mapping (mandragora style).**
- Why: Existing code reads `exc.status_code` in multiple places. Switching
to a pure domain exception + API-layer mapping dict would require changing
every consumer now, which is unnecessary churn in Phase 1.
- Alternative considered: mandragora's pattern (bare exceptions in core/,
status code mapping in api/error_handlers.py). Cleaner for hexagonal
purity but rejected for backward compatibility.
- Follow-up: strip status codes from core exceptions in Phase 10 when
api/error_handlers.py is built. The error handler will own the mapping.

---

## Template for future entries

```
Comment on lines 58 to 77

@coderabbitai coderabbitai Bot Apr 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Phase 1 section is inserted in the wrong place, creating a duplicate Template heading.

The pre-existing ## Template for future entries is still at line 58, the new Phase 1 content is dropped between it and its code fence, and a second ## Template for future entries is re-added at line 75. This both misplaces Phase 1 under the template heading and triggers markdownlint MD024. The Phase 1 block should go above the single template entry:

📝 Proposed fix 
 ---
 
-## Template for future entries
-
-## Phase 1 — Registry + Exceptions (2026-04-21)
+## Phase 1 — Registry + Exceptions (2026-04-21)
 
 **1. Exceptions keep HTTP status_code on the class (OpenRAG style), not in
 a separate error handler mapping (mandragora style).**
 ...
 - Follow-up: strip status codes from core exceptions in Phase 10 when
   api/error_handlers.py is built. The error handler will own the mapping.
 
 ---
 
 ## Template for future entries

Phase N — [short title] ([YYYY-MM-DD])

...

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
## Template for future entries
## Phase 1 — Registry + Exceptions (2026-04-21)
**1. Exceptions keep HTTP status_code on the class (OpenRAG style), not in
a separate error handler mapping (mandragora style).**
- Why: Existing code reads `exc.status_code` in multiple places. Switching
to a pure domain exception + API-layer mapping dict would require changing
every consumer now, which is unnecessary churn in Phase 1.
- Alternative considered: mandragora's pattern (bare exceptions in core/,
status code mapping in api/error_handlers.py). Cleaner for hexagonal
purity but rejected for backward compatibility.
- Follow-up: strip status codes from core exceptions in Phase 10 when
api/error_handlers.py is built. The error handler will own the mapping.
---
## Template for future entries
```
---
## Phase 1 — Registry + Exceptions (2026-04-21)
**1. Exceptions keep HTTP status_code on the class (OpenRAG style), not in
a separate error handler mapping (mandragora style).**
- Why: Existing code reads `exc.status_code` in multiple places. Switching
to a pure domain exception + API-layer mapping dict would require changing
every consumer now, which is unnecessary churn in Phase 1.
- Alternative considered: mandragora's pattern (bare exceptions in core/,
status code mapping in api/error_handlers.py). Cleaner for hexagonal
purity but rejected for backward compatibility.
- Follow-up: strip status codes from core exceptions in Phase 10 when
api/error_handlers.py is built. The error handler will own the mapping.
---
## Template for future entries
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)

[warning] 75-75: Multiple headings with the same content

(MD024, no-duplicate-heading)

[warning] 77-77: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@REFACTORING_DECISION_LOG.md` around lines 58 - 77, The Phase 1 block is
inserted inside and after the existing "## Template for future entries" header,
creating a duplicate template heading and MD024; move the entire "## Phase 1 —
Registry + Exceptions (2026-04-21)" section (including its content and the
trailing separator) so it appears above the single "## Template for future
entries" entry, remove the duplicate "## Template for future entries" that was
re-added, and ensure the template's closing code fence and formatting remain
intact; look for the headings "## Phase 1 — Registry + Exceptions (2026-04-21)"
and "## Template for future entries" to locate the blocks to reorder.

## Phase N — [short title] ([YYYY-MM-DD])

Expand Down
Empty file removed openrag/core/catalog/__init__.py
View file
Open in desktop
Empty file.
Loading
Loading