ordeal 0.0.0__tar.gz

ordeal-0.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,48 @@
+name: Bug Report
+description: Report a bug in ordeal
+labels: [bug]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Smallest code snippet or steps that trigger the bug.
+      render: python
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What should have happened instead?
+
+  - type: input
+    id: ordeal-version
+    attributes:
+      label: ordeal version
+      placeholder: "0.1.0"
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.12.0"
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: "Ubuntu 24.04 / macOS 15 / Windows 11"
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      render: text

ordeal-0.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

ordeal-0.0.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,24 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or use case
+      description: What are you trying to do? Why does ordeal not solve it today?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How should ordeal solve this? Include example API if applicable.
+      render: python
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What other approaches did you consider?

ordeal-0.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+## Summary
+
+<!-- What does this PR do? Why? -->
+
+## Test plan
+
+<!-- How was this tested? -->
+
+- [ ] Tests pass (`uv run pytest`)
+- [ ] Lint passes (`uv run ruff check .`)
+- [ ] New tests added for new functionality

ordeal-0.0.0/.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      dependencies:
+        patterns: ["*"]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      actions:
+        patterns: ["*"]

ordeal-0.0.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+
+      - run: uv python install 3.13
+
+      - run: uv sync --extra dev
+
+      - name: Ruff check
+        run: uv run ruff check .
+
+      - name: Ruff format
+        run: uv run ruff format --check .
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.12", "3.13"]
+        include:
+          - os: macos-latest
+            python-version: "3.13"
+          - os: windows-latest
+            python-version: "3.13"
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+
+      - run: uv python install ${{ matrix.python-version }}
+
+      - run: uv sync --extra dev
+
+      - name: Run tests
+        run: uv run pytest --tb=short -q

ordeal-0.0.0/.github/workflows/release.yml

@@ -0,0 +1,79 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+
+permissions: {}
+
+jobs:
+  # ── Auto-tag: bump patch on every push to main ──────────────────────
+  auto-tag:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      new_tag: ${{ steps.bump.outputs.new_tag }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Bump patch version
+        id: bump
+        run: |
+          # If HEAD already carries a version tag, skip (manual tag push).
+          if git tag --points-at HEAD | grep -qE '^v[0-9]'; then
+            echo "new_tag=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Find the latest clean semver tag (ignore pre-release suffixes).
+          LATEST=$(git tag -l 'v*' --sort=-v:refname \
+                   | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1)
+
+          if [ -z "$LATEST" ]; then
+            NEW_TAG="v0.0.1"
+          else
+            VERSION=${LATEST#v}
+            IFS='.' read -r MAJOR MINOR PATCH <<< "$VERSION"
+            NEW_TAG="v${MAJOR}.${MINOR}.$((PATCH + 1))"
+          fi
+
+          git tag "$NEW_TAG"
+          git push origin "$NEW_TAG"
+          echo "new_tag=$NEW_TAG" >> "$GITHUB_OUTPUT"
+
+  # ── Publish to PyPI ─────────────────────────────────────────────────
+  publish:
+    needs: [auto-tag]
+    # Run when: (a) triggered by a manual tag push, OR
+    #           (b) auto-tag just created a new tag.
+    if: >-
+      always() && (
+        startsWith(github.ref, 'refs/tags/v') ||
+        needs.auto-tag.outputs.new_tag != ''
+      )
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # OIDC for PyPI trusted publisher
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # setuptools-scm needs full history + tags
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build setuptools-scm
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ordeal-0.0.0/.gitignore

@@ -0,0 +1,211 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.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/
+cover/
+
+# 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
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.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/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Ordeal
+.ordeal/
+ordeal-report.json

ordeal-0.0.0/.python-version

@@ -0,0 +1 @@
+3.12

ordeal-0.0.0/AGENTS.md

@@ -0,0 +1,46 @@
+# AGENTS.md
+
+Conventions for AI agents working on ordeal.
+
+## Build & test
+
+```bash
+uv sync                          # install deps
+uv run pytest tests/ -q          # run all 205 tests (~7s)
+uv run pytest tests/ --chaos     # with property reporting
+uv run ordeal explore -c demo.toml  # run explorer (needs PYTHONPATH if tests/ is target)
+```
+
+## Project structure
+
+- `ordeal/` — library source (14 modules + faults/ + integrations/)
+- `tests/` — 13 test files, includes `test_battle.py` (ordeal testing itself)
+- `docs/` — 9 markdown docs, `index.md` is the hub
+- `ordeal.toml.example` — annotated config reference
+
+## Rules
+
+- Python 3.12+. Use `match/case`, `type | None` syntax, `from __future__ import annotations`.
+- Every public function has a docstring. Every parameter is typed. No untyped `Any` except at system boundaries (wrapping unknown functions, JSON codecs, optional deps).
+- Tests go in `tests/test_<module>.py`. Battle tests (ordeal testing itself) go in `tests/test_battle.py`.
+- Faults are in `ordeal/faults/{io,numerical,timing}.py`. New fault types go in the matching file or a new one.
+- No emojis in code or docs.
+- Keep docs under 130 lines each. Example-first, minimal prose.
+
+## Architecture decisions
+
+- `ChaosTest` extends Hypothesis's `RuleBasedStateMachine`. The nemesis rule is auto-injected.
+- The Explorer is separate from Hypothesis — it drives rules manually with coverage feedback.
+- `buggify()` is zero-cost in production (thread-local `_state.active` check).
+- Assertions use a global `PropertyTracker` — thread-safe, activated by `--chaos` flag or `auto_configure()`.
+- TOML config (`ordeal.toml`) is the interface between humans/agents and the Explorer.
+- Traces are JSON. Replay uses recorded param values, not re-drawing from strategies.
+
+## When adding a new feature
+
+1. Write the module in `ordeal/`.
+2. Add tests in `tests/test_<module>.py`.
+3. Add a battle test in `tests/test_battle.py` if the feature has interesting state.
+4. Export from `ordeal/__init__.py` if it's public API.
+5. Add a doc in `docs/` (under 130 lines).
+6. Update `docs/api-reference.md`.

ordeal-0.0.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- **ChaosTest** — stateful chaos testing with auto-injected nemesis, swarm mode
+- **Faults** — io, numerical, timing fault primitives + PatchFault/LambdaFault base
+- **Assertions** — always/sometimes/reachable/unreachable (Antithesis model)
+- **Invariants** — composable named checks (no_nan & bounded(0,1))
+- **Buggify** — FoundationDB-style inline fault injection
+- **QuickCheck** — @quickcheck decorator with boundary-biased generation
+- **Simulate** — Clock and FileSystem for no-mock testing
+- **Mutations** — AST-based mutation testing (arithmetic, comparison, negate, return_none)
+- **Explorer** — coverage-guided exploration with checkpointing, energy scheduling, shrinking
+- **Traces** — JSON recording, replay, delta-debugging shrinking
+- **CLI** — `ordeal explore` and `ordeal replay`
+- **Config** — `ordeal.toml` driven configuration
+- **Plugin** — pytest integration (--chaos, --chaos-seed, @pytest.mark.chaos)
+- **Integrations** — Atheris (coverage-guided fuzzing), Schemathesis (API chaos)

ordeal-0.0.0/CLAUDE.md

@@ -0,0 +1,108 @@
+# CLAUDE.md
+
+## Project
+
+ordeal — Automated chaos testing for Python. Fault injection, property assertions, coverage-guided exploration, and stateful testing in one library.
+
+Built on ideas from Antithesis (deterministic exploration), FoundationDB (BUGGIFY inline faults), Jepsen (nemesis interleaving), Hypothesis (stateful property testing), Jane Street QuickCheck (boundary-biased generation), and Meta ACH (mutation validation).
+
+## Commands
+
+```bash
+uv sync                          # install dependencies
+uv run pytest                    # run all tests (~205 tests)
+uv run pytest tests/test_X.py    # single module
+uv run pytest -x                 # stop on first failure
+uv run pytest --chaos            # enable chaos mode in tests
+uv run pytest --chaos-seed 42    # reproducible chaos
+uv run ruff check .              # lint
+uv run ruff format --check .     # check formatting
+uv run ruff format .             # auto-format
+uv run ordeal explore            # run coverage-guided explorer (reads ordeal.toml)
+uv run ordeal replay <trace>     # replay a failure trace
+```
+
+## Architecture
+
+```
+ordeal/
+├── __init__.py         Public API: ChaosTest, rule, invariant, always, sometimes, buggify, etc.
+├── chaos.py            ChaosTest base class (extends Hypothesis RuleBasedStateMachine)
+├── explore.py          Coverage-guided explorer — AFL-style edge hashing, energy scheduling
+├── assertions.py       always / sometimes / reachable / unreachable (Antithesis model)
+├── buggify.py          Inline fault injection (FoundationDB BUGGIFY model)
+├── quickcheck.py       @quickcheck decorator with boundary-biased type-driven strategies
+├── simulate.py         Deterministic simulation primitives: Clock, FileSystem
+├── invariants.py       Composable invariants with & operator: no_nan & bounded(0, 1)
+├── mutations.py        AST-based mutation testing with 4 operators
+├── trace.py            Trace recording, JSON serialization, replay, delta-debugging shrink
+├── config.py           ordeal.toml loader with strict validation
+├── cli.py              CLI entry point: ordeal explore / ordeal replay
+├── plugin.py           Pytest plugin: --chaos, --chaos-seed, --buggify-prob flags
+├── strategies.py       Adversarial Hypothesis strategies for fuzzing
+├── faults/
+│   ├── __init__.py     Fault / PatchFault / LambdaFault base abstractions
+│   ├── io.py           error_on_call, disk_full, permission_denied, corrupt/truncate output
+│   ├── numerical.py    nan_injection, inf_injection, wrong_shape, corrupted_floats
+│   └── timing.py       timeout, slow, intermittent_crash, jitter
+└── integrations/
+    ├── atheris_engine.py    Coverage-guided fuzzing bridge (optional: atheris)
+    └── schemathesis_ext.py  API chaos testing bridge (optional: schemathesis)
+```
+
+## Key design decisions
+
+- **ChaosTest** extends `hypothesis.stateful.RuleBasedStateMachine`. A **nemesis rule** is auto-injected to toggle faults during exploration. Hypothesis explores rule interleavings + fault schedules.
+- **Swarm mode**: Each test run uses a random subset of faults. Better aggregate coverage than all-faults-always-on.
+- **Energy scheduling**: Checkpoints that led to new edge coverage get higher selection probability. Constants: reward=2.0, decay=0.95, min=0.01.
+- **Assertions**: `always`/`unreachable` raise immediately (triggers Hypothesis shrinking). `sometimes`/`reachable` are deferred — checked at session end via PropertyTracker.
+- **buggify()**: No-op when chaos mode is inactive. Thread-local RNG, seed-controlled, zero overhead in production.
+- **PatchFault**: Resolves a dotted path (e.g. `"myapp.api.call"`) and wraps the target function with fault behavior. Activate/deactivate cycle managed by ChaosTest.
+- **Optional deps**: atheris, schemathesis, numpy are behind try/except imports with helpful error messages.
+
+## Conventions
+
+- Python >= 3.12. Type hints throughout.
+- `ruff` for lint and format. Line length 99. Rules: E, F, I, W.
+- Tests in `tests/`. Test files prefixed `test_*.py`. Helper modules prefixed `_*.py`.
+- Configuration via `ordeal.toml` — see `ordeal.toml.example` for full schema.
+- Hypothesis stateful API (`rule`, `invariant`, `initialize`, `precondition`, `Bundle`) is re-exported from `ordeal.__init__`.
+- Version derived from git tags via `setuptools-scm`.
+
+## Dependencies
+
+- **Required**: hypothesis >= 6.100.0, pytest >= 8.0.0
+- **Optional extras**:
+  - `ordeal[atheris]` — coverage-guided fuzzing via Google Atheris
+  - `ordeal[api]` — API chaos testing via Schemathesis
+  - `ordeal[all]` — everything including numpy
+- **Dev**: ruff, pytest-cov (`pip install ordeal[dev]`)
+
+## Common tasks
+
+### Add a new fault type
+
+1. Add a function in the appropriate `ordeal/faults/*.py` module that returns a `PatchFault` or `LambdaFault`.
+2. The function takes a `target` dotted path and fault-specific parameters.
+3. Add tests in `tests/test_faults.py`.
+4. Document in `docs/api-reference.md`.
+
+### Add a new assertion
+
+1. Add the function in `ordeal/assertions.py`.
+2. If deferred (like `sometimes`), register with the global `tracker: PropertyTracker`.
+3. Export from `ordeal/__init__.py` and add to `__all__`.
+4. Add tests in `tests/test_assertions.py`.
+
+### Add a new invariant
+
+1. Add a function in `ordeal/invariants.py` that returns an `Invariant` instance.
+2. Invariants compose with `&`. Numpy support is optional — guard with try/except.
+3. Add tests in `tests/test_invariants.py`.
+
+### Add a new mutation operator
+
+1. Create an AST `NodeTransformer` subclass in `ordeal/mutations.py`.
+2. Register it in `_APPLICATORS` dict with a string key.
+3. The applicator yields `Mutant` objects with location and description.
+4. Add tests in `tests/test_battle.py` or a dedicated test file.

ordeal-0.0.0/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to ordeal
+
+## Setup
+
+```bash
+git clone https://github.com/teilomillet/ordeal
+cd ordeal
+uv sync --extra dev
+```
+
+## Development workflow
+
+```bash
+uv run pytest                    # run tests
+uv run pytest tests/test_X.py    # single module
+uv run pytest -x                 # stop on first failure
+uv run ruff check .              # lint
+uv run ruff format .             # format
+```
+
+## Submitting changes
+
+1. Fork the repo and create a branch from `main`.
+2. Write tests for your changes.
+3. Ensure `uv run pytest` and `uv run ruff check .` pass.
+4. Open a pull request.
+
+## Project structure
+
+See [CLAUDE.md](CLAUDE.md) for architecture, conventions, and common contribution recipes.
+
+## Adding a new fault type
+
+1. Create a function in `ordeal/faults/` that returns a `PatchFault` or `LambdaFault`.
+2. Add tests in `tests/test_faults.py`.
+3. Document in `docs/api-reference.md`.
+
+## Adding a new assertion
+
+1. Add the function in `ordeal/assertions.py`.
+2. Export from `ordeal/__init__.py` and add to `__all__`.
+3. Add tests in `tests/test_assertions.py`.