domain-errors 0.1.0__tar.gz

domain_errors-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug report
+about: Report a bug or unexpected behavior
+title: ''
+labels: 'bug'
+---
+
+## Description
+
+A clear, concise description of what the bug is.
+
+## Steps to Reproduce
+
+1. 
+2. 
+3. 
+
+## Expected Behavior
+
+What should happen?
+
+## Actual Behavior
+
+What actually happened instead?
+
+## Environment
+
+- Python version: 
+- domain-errors version: 
+- OS: 
+
+## Additional Context
+
+Any other context, code snippets, or error messages that help clarify the issue.

domain_errors-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature request
+about: Suggest an idea for domain-errors
+title: ''
+labels: 'enhancement'
+---
+
+## Problem Statement
+
+What problem or use case would this feature address? What is the pain point today?
+
+## Proposed Solution
+
+How should this feature work? Describe the behavior and any new APIs or changes.
+
+## Alternatives
+
+Have you considered other approaches? What are the trade-offs?
+
+## Additional Context
+
+Any examples, code sketches, or related issues that provide context.

domain_errors-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,37 @@
+## Description
+
+What does this PR do? Why is the change needed?
+
+## Related Issue(s)
+
+Closes #
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] Feature addition
+- [ ] Documentation update
+- [ ] Refactoring
+- [ ] Dependency update
+
+## Testing
+
+How has this been tested? What test cases are included?
+
+- [ ] Unit tests added/updated
+- [ ] Tests pass locally (`uv run pytest`)
+
+## Code Quality
+
+- [ ] Style checks pass (`uv run ruff check` and `uv run ruff format`)
+- [ ] Type checking passes (`uv run mypy` and `uv run pyright`)
+- [ ] Documentation and docstrings updated
+- [ ] CHANGELOG.md updated (if applicable)
+- [ ] No co-author or AI attribution trailers in commits
+
+## Checklist
+
+- [ ] I have read [CONTRIBUTING.md](../CONTRIBUTING.md)
+- [ ] I have followed the project's code style and conventions
+- [ ] My commits follow the commit message guidelines (no attribution trailers)
+- [ ] All checks pass locally before opening this PR

domain_errors-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Install Python
+        run: uv python install ${{ matrix.python-version }}
+      - name: Sync dependencies
+        run: uv sync --all-extras
+      - name: Test
+        # Collection probe: pytest exit 5 = no tests collected (skeleton stage);
+        # once the first suite lands, the full coverage-gated run applies.
+        run: |
+          set +e
+          uv run pytest --collect-only -q
+          collect=$?
+          set -e
+          if [ "$collect" -eq 5 ]; then
+            echo "No tests collected yet; skeleton stage."
+            exit 0
+          fi
+          uv run pytest -v --cov --cov-fail-under=95
+
+  mypy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Install Python 3.12
+        run: uv python install 3.12
+      - name: Sync dependencies
+        run: uv sync --all-extras
+      - name: Type-check
+        run: uv run mypy domain_errors/

domain_errors-0.1.0/.github/workflows/cleanup-guard.yml

@@ -0,0 +1,70 @@
+name: Cleanup Guard
+
+on:
+  pull_request
+
+jobs:
+  feature-documentation:
+    name: Verify all features have audit and review docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check feature documentation completeness
+        run: |
+          set -e
+
+          echo "Checking that all implemented features have audit and review documentation..."
+
+          AUDITS_DIR="docs/audits"
+          REVIEWS_DIR="docs/reviews"
+
+          FEATURES_DIRS="domain_errors/services domain_errors/domains"
+          FEATURES=""
+          for FEATURES_DIR in $FEATURES_DIRS; do
+            if [ -d "$FEATURES_DIR" ]; then
+              FEATURES="$FEATURES $(find "$FEATURES_DIR" -maxdepth 1 -type d ! -name "__pycache__" ! -name "tests" ! -name "constants" ! -path "$FEATURES_DIR")"
+            fi
+          done
+
+          if [ -z "$FEATURES" ]; then
+            echo "ERROR: No features found in domain_errors/services/ or domain_errors/domains/"
+            exit 1
+          fi
+
+          MISSING_DOCS=0
+
+          for feature_dir in $FEATURES; do
+            feature_name=$(basename "$feature_dir")
+
+            # Skip features with no source files
+            if [ -z "$(find "$feature_dir" -maxdepth 1 -type f -name '*.py')" ]; then
+              continue
+            fi
+
+            # Skip features that are not implemented yet (docstring-only stubs, no classes or functions)
+            if ! grep -lqE '^(class |def )' "$feature_dir"/*.py 2>/dev/null; then
+              echo "SKIP: feature '$feature_name' has no implementation yet"
+              continue
+            fi
+
+            audit_file=$(find "$AUDITS_DIR" -name "*$feature_name*audit*" 2>/dev/null | head -1)
+            review_file=$(find "$REVIEWS_DIR" -name "*$feature_name*review*" 2>/dev/null | head -1)
+
+            if [ -z "$audit_file" ]; then
+              echo "FAIL: feature '$feature_name' missing audit doc in $AUDITS_DIR"
+              MISSING_DOCS=$((MISSING_DOCS + 1))
+            fi
+
+            if [ -z "$review_file" ]; then
+              echo "FAIL: feature '$feature_name' missing review doc in $REVIEWS_DIR"
+              MISSING_DOCS=$((MISSING_DOCS + 1))
+            fi
+          done
+
+          if [ $MISSING_DOCS -gt 0 ]; then
+            echo ""
+            echo "ERROR: $MISSING_DOCS feature(s) missing documentation."
+            exit 1
+          fi
+
+          echo "All implemented features have corresponding audit and review docs."

domain_errors-0.1.0/.github/workflows/dto-strict.yml

@@ -0,0 +1,36 @@
+name: dto-strict
+
+# DTO-discipline lint (frozen+slots, facade-ban, R001-R006). Per-repo copy of
+# the canonical gate; runs on the root-layout package. Empty baseline at
+# v0.3.0 (clean rebuild — 0 violations).
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Install Python 3.12
+        run: uv python install 3.12
+      - name: Run dto-strict
+        run: uvx --python 3.12 dto-strict@0.4.0 domain_errors/ --format github
+      - name: Check LOC cap (source dirs only)
+        run: |
+          # LOC-cap step: source dirs only (test density exempt from cap per review record)
+          for dir in domain_errors/common/constants domain_errors/config domain_errors/services/chain domain_errors/services/constants domain_errors/domains/domain_error domain_errors/domains/python domain_errors/domains/http domain_errors/domains/botocore domain_errors/domains/constants; do
+            uvx --python 3.12 dto-strict@0.4.0 loc-cap "$dir"
+          done

domain_errors-0.1.0/.github/workflows/no-ai-attribution.yml

@@ -0,0 +1,73 @@
+name: Attribution Gate
+
+# Server-side enforcement: rejects pushes/PRs whose commit messages contain
+# Claude/Anthropic attribution. Catches GitHub squash-merge propagation that
+# bypasses local commit-msg, pre-push, and PreToolUse hooks.
+#
+# Per-repo copy of the canonical attribution gate.
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  scan:
+    name: Scan commit messages for attribution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout (full history)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Determine commit range
+        id: range
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          PR_BASE: ${{ github.event.pull_request.base.sha }}
+          PR_HEAD: ${{ github.event.pull_request.head.sha }}
+          PUSH_BEFORE: ${{ github.event.before }}
+          PUSH_AFTER: ${{ github.event.after }}
+        run: |
+          set -euo pipefail
+          if [ "$EVENT_NAME" = "pull_request" ]; then
+            BASE="$PR_BASE"
+            HEAD="$PR_HEAD"
+          else
+            BASE="$PUSH_BEFORE"
+            HEAD="$PUSH_AFTER"
+            if [ "$BASE" = "0000000000000000000000000000000000000000" ] || [ -z "$BASE" ]; then
+              git fetch origin main:refs/remotes/origin/main 2>/dev/null || true
+              BASE=$(git merge-base origin/main "$HEAD" 2>/dev/null || git rev-list --max-parents=0 "$HEAD" | tail -1)
+            fi
+          fi
+          echo "base=$BASE" >> "$GITHUB_OUTPUT"
+          echo "head=$HEAD" >> "$GITHUB_OUTPUT"
+
+      - name: Scan for Claude/Anthropic attribution
+        env:
+          BASE: ${{ steps.range.outputs.base }}
+          HEAD: ${{ steps.range.outputs.head }}
+          PATTERN: 'co-authored-by.*(claude|anthropic)|generated with claude|@claude|noreply@anthropic|🤖'
+        run: |
+          set -uo pipefail
+          OFFENDING=""
+          for sha in $(git rev-list "$BASE..$HEAD"); do
+            MSG=$(git log -1 --pretty=format:"%B" "$sha")
+            if echo "$MSG" | grep -qiE "$PATTERN"; then
+              AUTHOR=$(git log -1 --pretty=format:"%an" "$sha")
+              SUBJECT=$(git log -1 --pretty=format:"%s" "$sha")
+              OFFENDING="${OFFENDING}  ${sha:0:8} | author=${AUTHOR} | ${SUBJECT}"$'\n'
+            fi
+          done
+          if [ -n "$OFFENDING" ]; then
+            echo "::error::Claude/Anthropic attribution detected in commit messages"
+            echo "Offending commits in range $BASE..$HEAD:"
+            printf '%s' "$OFFENDING"
+            exit 1
+          fi
+          echo "OK: no attribution detected in $BASE..$HEAD"

domain_errors-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    name: Build + publish
+    runs-on: ubuntu-latest
+    environment: pypi  # second-layer GitHub deployment-environment gate
+    permissions:
+      id-token: write  # OIDC trusted publisher
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build deps
+        run: python -m pip install --upgrade build
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - name: Verify artifacts
+        run: python -m pip install --upgrade twine && python -m twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

domain_errors-0.1.0/.github/workflows/ruff.yml

@@ -0,0 +1,29 @@
+name: Ruff
+
+# Ruff lint + format check. Pinned to 0.15.14 to match local version.
+# Format drift was previously undetected; this gate prevents future drift.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Ruff lint
+        run: uvx ruff@0.15.14 check domain_errors/
+      - name: Ruff format check
+        run: uvx ruff@0.15.14 format --check domain_errors/

domain_errors-0.1.0/.gitignore

@@ -0,0 +1,134 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# uv
+.venv
+.venv.lock

domain_errors-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-15
+
+### Added
+
+- **DomainError base class:** Typed exception hierarchy with class contract (code, domain, http_status, retryable, default_message).
+- **Instance state:** message (string) and context (dict) for structured logging.
+- **ErrorChain service:** Static methods for wrapping, walking, and analyzing exception chains.
+  - `wrap(err, as_=ErrorType, message=None, **context)` — construct typed domain errors.
+  - `history(err, classifiers=())` — walk exception cascade into ChainLink objects.
+  - `crossings(err, classifiers=())` — identify domain boundary crossings.
+- **ChainLink value object:** Structured representation of one exception chain hop, with `to_log_extra()` for JSON-ready logging.
+- **DomainCrossing value object:** Causation hop where errors cross domain boundaries, with `to_log_extra()` for logging.
+- **ChainVia enum:** Tags for how a link entered the chain (ROOT, CAUSE, CONTEXT).
+- **DomainClassifier protocol:** Contract for resolving domains of foreign (non-DomainError) exceptions.
+- **Python stdlib domain classifier:** Built-in `python` classifier for mapping stdlib exception families (network, OS, logic, assertion) to domain strings.
+- **HTTP-client domain classifier:** Built-in `http` classifier for mapping httpx, requests, and aiohttp exceptions to the http domain. By-origin design (type(err).__module__) catches the entire library surface including exceptions outside main error trees; no runtime dependency on the libraries.
+- **AWS cloud domain classifier:** Built-in `cloud` classifier for mapping botocore and boto3 exceptions to the cloud domain. By-origin design (type(err).__module__) catches the entire AWS SDK surface; no runtime dependency on the libraries.
+- **@wrap_errors decorator:** Declarative error wrapping for functions and async callables. Catches specified exceptions, wraps them into a target DomainError via ErrorChain.wrap(), and preserves causation via raise-from. Captures function arguments into error context for structured logging (disable via capture=False). DomainError instances pass through unchanged. Works on both sync and async functions.
+- **Logging payload DTOs:** LinkLogExtra and CrossingLogExtra for structured audit trails.

domain_errors-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Code of Conduct
+
+## My Commitment
+
+I maintain this project solo, and I am committed to keeping it a welcoming space for everyone who participates in issues, pull requests, and discussions. I pledge to treat every participant with respect and dignity, regardless of age, body size, caste, disability, ethnicity, sex characteristics, gender, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, sexual identity and orientation, or any other dimension of diversity.
+
+## Standards
+
+Behavior that keeps this a positive space:
+
+- Welcoming and inclusive language
+- Respect for differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the project
+- Empathy toward other participants
+
+Behavior I will not accept:
+
+- Harassment or insulting or derogatory comments
+- Personal attacks
+- Public or private harassment
+- Publishing someone's private information without consent
+- Conduct that could reasonably be considered inappropriate
+
+## Enforcement
+
+Report unacceptable behavior to me through GitHub, either by opening an issue or, where discretion is warranted, through private vulnerability reporting. I review and act on every report promptly and fairly, and I respect the privacy and security of anyone who reports.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

domain_errors-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing
+
+Thank you for your interest in contributing to domain-errors. This guide explains how to set up your development environment, run tests and linters, and follow our code standards.
+
+## Development Setup
+
+This project uses **uv** for dependency management. Install it first, then sync dependencies:
+
+```bash
+uv sync
+```
+
+This creates a virtual environment and installs all development dependencies, including testing, linting, type-checking, and formatting tools.
+
+## Running Checks
+
+All checks must pass before code is merged:
+
+```bash
+# Run tests
+uv run pytest
+
+# Check code style and imports
+uv run ruff check
+
+# Format code
+uv run ruff format
+
+# Type check (mypy)
+uv run mypy
+
+# Type check (pyright alternative)
+uv run pyright
+```
+
+Run these locally before opening a pull request to catch issues early.
+
+## Code Style
+
+This project follows these conventions:
+
+- **Dataclasses**: Use `@dataclass(frozen=True, slots=True)` for immutable value types.
+- **Docstrings**: One-line docstrings for modules, classes, and functions. Use triple quotes even for single lines.
+- **Imports**: Import abstract base classes from `collections.abc` (not `typing`). Use absolute imports (no relative imports).
+- **Methods**: Every method lives in a class or container—no module-level functions. Containers keep methods organized.
+- **Constants**: Extract magic constants to `constants/` directory only when they are semantically significant (shared across modules or define behavior).
+
+## Pull Request Flow
+
+1. **Branch**: Create a feature branch off `main` (e.g., `git checkout -b feature/my-feature`).
+2. **Commit**: Make small, clear commits. Each commit author is the person who wrote the code—no co-author or AI attribution trailers.
+3. **Push**: Push your branch and open a pull request on GitHub.
+4. **Review**: The maintainer will review your code, request changes if needed, and merge when ready. Contributors do not merge their own PRs.
+
+## Commit Messages
+
+Write clear, descriptive commit messages that explain *why* the change was made. Example:
+
+```
+Add @wrap_errors decorator for automatic error domain wrapping
+
+Simplifies error handling across services by applying domain
+classification to function arguments without try/except boilerplate.
+```
+
+Do not include co-author or AI attribution trailers in commit messages.
+
+## Community Standards
+
+Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before participating. We expect respectful collaboration and inclusive language in all interactions.