Add error handling with Result type and document architecture decisions

.github/workflows/python-tests.yml

@@ -7,7 +7,7 @@ on:
     branches: [ main, master ]
 
 jobs:
-  test:
+  test-and-typecheck:
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -15,15 +15,17 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install -r requirements.txt
-          pip install pytest
-      - name: Run tests
+          pip install pytest mypy
+      - name: Run pytest
         run: |
-          python -m unittest discover -v
-          pytest -q || true
+          python -m pytest -q
+      - name: Run mypy (strict)
+        run: |
+          python -m mypy --config-file mypy.ini