Metadata-Version: 2.4
Name: difftrial
Version: 0.1.0
Summary: A bounded red-to-green regression-transition verifier for Git repositories.
Author: Shree Dharshan Santhagunam
Maintainer: Shree Dharshan Santhagunam
License-Expression: Apache-2.0
Project-URL: Source, https://github.com/ShreeDharshan/difftrial
Project-URL: Issues, https://github.com/ShreeDharshan/difftrial/issues
Project-URL: Changelog, https://github.com/ShreeDharshan/difftrial/releases
Keywords: git,pytest,regression testing,verification
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: POSIX
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pytest>=7.4
Dynamic: license-file

# DiffTrial

DiffTrial is a bounded red-to-green regression-transition verifier for Git
repositories. It checks one tracked evidence file against a committed base and
candidate revision: the base must fail for the expected deterministic reason, the
candidate must pass, and selected shared regression tests must not regress.

This is bounded evidence, not proof of complete correctness.

## Install

From PyPI:

```shell
python -m pip install difftrial
```

From a source checkout:

```shell
python -m pip install .
```

## Example

Suppose the base commit contains:

```python
# app.py
def value():
    return 1
```

```python
# tests/test_regression.py
from app import value

def test_value_is_positive():
    assert value() > 0
```

The candidate commit changes `value()` to return `2` and adds this tracked
evidence file:

```python
# tests/test_selected.py
from app import value

def test_value():
    assert value() == 2
```

With both revisions committed and the candidate checked out at `HEAD`, run:

```shell
difftrial verify --base HEAD^ --evidence tests/test_selected.py \
  --test-id tests/test_selected.py::test_value \
  --phase call --outcome failed \
  --exception-category AssertionError \
  --regression tests/test_regression.py
```

The same tracked evidence is overlaid onto the base worktree and tested with the
same supplied interpreter and environment. A successful run emits a report such
as:

```text
# DiffTrial verification report
- Verdict: VERIFIED_TRANSITION
```

The baseline failure contract is matched exactly by phase and outcome, with
optional exception category, assertion signature, and output fragments. An
assertion signature is the exact normalised failure message captured from pytest,
which can include evaluated values rather than the original source expression.

Exit codes are 0 for a verified transition, 1 for a completed but unverified
transition, 2 for usage or input errors, and 3 for expected operational or
infrastructure failures.

## Boundaries

DiffTrial targets Python 3.11–3.13 on POSIX systems. macOS is locally verified,
and Linux is verified through GitHub Actions. Windows is unverified and unsupported
for v0.1. Execution is trusted-local-only and is not a sandbox: do not run code
the operator does not trust.

The candidate tree must be clean and committed. v0.1 applies exactly one tracked
candidate evidence file to the base. Reports may contain absolute paths, repository
details, and captured test output. The Python API and experimental JSON schema may
change before 1.0.

Report ordinary bugs through
[GitHub Issues](https://github.com/ShreeDharshan/difftrial/issues). Follow
[SECURITY.md](https://github.com/ShreeDharshan/difftrial/blob/main/SECURITY.md)
for sensitive reports.

## Development

```shell
python -m pytest
```
