due-work-harness 0.1.0__tar.gz

due_work_harness-0.1.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

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

@@ -0,0 +1,205 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# Every job installs from uv.lock with --locked: a lock that no longer matches
+# pyproject.toml fails CI instead of silently resolving something new.
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --locked --only-group lint
+      - run: uv run --no-sync ruff check
+      - run: uv run --no-sync ruff format --check
+      - name: actionlint
+        run: docker run --rm -v "$PWD:/repo" -w /repo rhysd/actionlint:1.7.7 -color
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      # The demos type-check against the upstream code they run (Saleor's in its own job).
+      - run: uv run --no-project python demos/fetch_upstream.py procrastinate dbos-demo-apps
+      - run: uv sync --locked --all-extras --group demos
+      - run: uv pip install -e demos/.upstream/procrastinate
+      - run: uv run --no-sync pyrefly check
+
+  core:
+    # The core must work with no framework installed: the package and pytest only.
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked --no-default-groups
+      - run: uv run --no-sync python scripts/check_core_is_framework_free.py
+      - run: uv run --no-sync pytest tests/core
+
+  django:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd pg_isready --health-interval 5s --health-timeout 5s --health-retries 10
+    env:
+      PGHOST: localhost
+      PGUSER: postgres
+      PGPASSWORD: postgres
+      PGPORT: "5432"
+      PGDATABASE: due_work_harness
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --locked --no-default-groups --extra django --extra celery
+      - run: uv run --no-sync pytest tests/django --ds=tests.django.settings
+
+  demos:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd pg_isready --health-interval 5s --health-timeout 5s --health-retries 10
+    env:
+      PGHOST: localhost
+      PGUSER: postgres
+      PGPASSWORD: postgres
+      PGPORT: "5432"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # The check action builds the harness from this checkout; its version comes from git tags.
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv run --no-project python demos/fetch_upstream.py procrastinate dbos-demo-apps
+      - run: uv sync --locked --no-default-groups --extra django --group demos
+      # procrastinate's demos ship only in its source tree, pinned by fetch_upstream.py.
+      - run: uv pip install -e demos/.upstream/procrastinate
+      - name: procrastinate demo_django
+        env:
+          PGDATABASE: procrastinate_demo
+        run: uv run --no-sync pytest demos/procrastinate_demo_django --ds=demos.procrastinate_demo_django.settings -rxX
+      - name: DBOS transactional-outbox
+        run: uv run --no-sync pytest demos/dbos_transactional_outbox -p no:django -rxX
+      # Each demo is an adopter: its handoffs are checked the way an adopter's CI checks them.
+      - name: procrastinate demo_django, every handoff accounted for
+        uses: ./check
+        with:
+          working-directory: demos/procrastinate_demo_django
+          package: ${{ github.workspace }}
+      - name: DBOS transactional-outbox, every handoff accounted for
+        uses: ./check
+        with:
+          working-directory: demos/dbos_transactional_outbox
+          package: ${{ github.workspace }}
+
+  saleor:
+    # Saleor's checkout, unmodified, in Saleor's own environment built from its uv.lock.
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd pg_isready --health-interval 5s --health-timeout 5s --health-retries 10
+    env:
+      DATABASE_URL: postgres://postgres:postgres@localhost:5432/saleor
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # The check action builds the harness from this checkout; its version comes from git tags.
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          # Saleor's pin lives in fetch_upstream.py; its lock is fetched after this step.
+          cache-dependency-glob: |
+            uv.lock
+            demos/fetch_upstream.py
+      - run: uv run --no-project python demos/fetch_upstream.py saleor
+      - name: Type-check the demo against Saleor
+        run: demos/saleor_checkout/run.sh --typecheck
+      - name: Saleor, every handoff accounted for
+        uses: ./check
+        with:
+          working-directory: demos/saleor_checkout
+          package: ${{ github.workspace }}
+      - name: Saleor checkout
+        run: demos/saleor_checkout/run.sh -rxX --due-work-verify
+
+  build:
+    # The published wheel alone: it installs without any framework, imports, and ships py.typed.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # The version is derived from tags, so build with the history that has them.
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv build
+      - run: unzip -l dist/*.whl | grep -q "due_work_harness/py.typed"
+      - run: uv venv /tmp/wheel && uv pip install --python /tmp/wheel dist/*.whl
+      - run: /tmp/wheel/bin/python scripts/check_core_is_framework_free.py
+
+  actions:
+    # The published GitHub Actions, run against the example adopter the way a project would use them.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: check passes on a project whose every handoff is accounted for
+        uses: ./check
+        with:
+          working-directory: examples/adopter
+          package: ${{ github.workspace }}
+      - name: test runs the project's generated suites
+        uses: ./test
+        with:
+          working-directory: examples/adopter
+      - name: check fails once a handoff loses its disposition
+        run: |
+          rm examples/adopter/tests/test_summaries_exemption.py
+          if uvx --from "$GITHUB_WORKSPACE" due-work-harness check --root examples/adopter; then
+            echo "::error::the check passed a project with an unaccounted handoff" >&2
+            exit 1
+          fi

due_work_harness-0.1.0/.github/workflows/pr-title.yml

@@ -0,0 +1,34 @@
+name: PR title
+
+# Pull requests are squash-merged with their title as the commit message, and
+# release-please reads those commits to choose the next version. The title must
+# therefore be a Conventional Commit: see RELEASING.md.
+
+on:
+  pull_request_target:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  conventional-commit:
+    runs-on: ubuntu-latest
+    steps:
+      # Reads only the title through the API; it never checks out the pull request's code.
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            perf
+            revert
+            docs
+            refactor
+            test
+            build
+            ci
+            chore
+          requireScope: false

due_work_harness-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,193 @@
+name: Release
+
+# On every push to main, release-please updates a release PR holding the next
+# SemVer version and changelog, derived from Conventional Commit messages.
+# Merging that PR tags vX.Y.Z and creates the GitHub release; this workflow
+# then builds that exact tag and publishes it to PyPI with Trusted Publishing
+# (OIDC, no stored token). See RELEASING.md.
+#
+# workflow_dispatch publishes an existing tag to TestPyPI or PyPI (a rehearsal,
+# or a publish that failed after tagging), or, with no tag and TestPyPI, the
+# dispatched commit's .devN version, which PyPI never receives.
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag to publish, for example v0.1.0. Empty with testpypi: publish this commit's dev version"
+        required: false
+        default: ""
+      index:
+        description: "Where to publish"
+        type: choice
+        options: [testpypi, pypi]
+        default: testpypi
+
+permissions: {}
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - id: release
+        uses: googleapis/release-please-action@v4
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  build:
+    needs: release-please
+    if: >-
+      always() && (
+        (github.event_name == 'push' && needs.release-please.result == 'success' && needs.release-please.outputs.release_created == 'true')
+        || github.event_name == 'workflow_dispatch'
+      )
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      tag: ${{ steps.tag.outputs.tag }}
+      version: ${{ steps.built.outputs.version }}
+    steps:
+      - id: tag
+        env:
+          TAG: ${{ needs.release-please.outputs.tag_name || inputs.tag }}
+          INDEX: ${{ inputs.index || 'pypi' }}
+        run: |
+          if [[ -z "$TAG" ]]; then
+            # Only a TestPyPI rehearsal may publish an untagged commit, as its .devN version.
+            if [[ "$INDEX" != "testpypi" ]]; then
+              echo "::error::publishing to PyPI needs a release tag" >&2
+              exit 1
+            fi
+            echo "tag=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          # A release is a plain SemVer core version: vMAJOR.MINOR.PATCH.
+          if [[ ! "$TAG" =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then
+            echo "::error::'$TAG' is not a release tag of the form vMAJOR.MINOR.PATCH" >&2
+            exit 1
+          fi
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ steps.tag.outputs.tag || github.sha }}
+          # The version is read from the tag, so the tag must be present.
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - name: The built version is the tag
+        if: steps.tag.outputs.tag != ''
+        env:
+          VERSION: ${{ steps.tag.outputs.version }}
+        run: |
+          ls dist
+          test -f "dist/due_work_harness-${VERSION}-py3-none-any.whl"
+          test -f "dist/due_work_harness-${VERSION}.tar.gz"
+      - name: An untagged build is a dev release
+        if: steps.tag.outputs.tag == ''
+        run: |
+          ls dist
+          wheel=$(basename dist/*.whl)
+          [[ "$wheel" =~ ^due_work_harness-[0-9]+\.[0-9]+(\.[0-9]+)?\.dev[0-9]+-py3-none-any\.whl$ ]]
+      - id: built
+        run: |
+          wheel=$(basename dist/*.whl)
+          version=${wheel#due_work_harness-}
+          echo "version=${version%-py3-none-any.whl}" >> "$GITHUB_OUTPUT"
+      - name: The wheel alone installs, imports without any framework, and is typed
+        run: |
+          unzip -l dist/*.whl | grep -q "due_work_harness/py.typed"
+          uv venv /tmp/wheel && uv pip install --python /tmp/wheel dist/*.whl
+          /tmp/wheel/bin/python scripts/check_core_is_framework_free.py
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    needs: build
+    if: >-
+      always() && needs.build.result == 'success'
+      && (github.event_name == 'push' || inputs.index == 'pypi')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/due-work-harness/${{ needs.build.outputs.version }}/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-testpypi:
+    needs: build
+    if: >-
+      always() && needs.build.result == 'success'
+      && github.event_name == 'workflow_dispatch' && inputs.index == 'testpypi'
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/due-work-harness/${{ needs.build.outputs.version }}/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  attach-to-release:
+    needs: [build, publish-pypi]
+    if: always() && needs.publish-pypi.result == 'success' && needs.build.outputs.tag != ''
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.build.outputs.tag }}
+        run: gh release upload "$TAG" dist/* --clobber --repo "$GITHUB_REPOSITORY"
+
+  move-major-tag:
+    # `uses: gigaverse-app/due-work-harness/check@v0` follows the latest v0.x.y release.
+    needs: [build, publish-pypi]
+    if: always() && needs.publish-pypi.result == 'success' && needs.build.outputs.tag != ''
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ needs.build.outputs.tag }}
+      - env:
+          TAG: ${{ needs.build.outputs.tag }}
+        run: |
+          MAJOR="${TAG%%.*}"
+          git tag --force "$MAJOR" "$TAG"
+          git push --force origin "refs/tags/$MAJOR"

due_work_harness-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv*/
+__pycache__/
+*.pyc
+.upstream_tests/
+/dist/
+/build/
+*.egg-info/
+demos/.upstream/
+demos/dbos_transactional_outbox/.inbox.txt

due_work_harness-0.1.0/.python-version

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

due_work_harness-0.1.0/.release-please-manifest.json

@@ -0,0 +1 @@
+{".":"0.1.0"}

due_work_harness-0.1.0/ADOPTING.md

@@ -0,0 +1,163 @@
+# Adopting due-work-harness
+
+This is the path from "we use Django/Celery, Procrastinate or DBOS" to "CI fails
+when background work can be lost or repeated". A complete, minimal adopter lives
+in [`examples/adopter/`](examples/adopter/); the harness's own CI runs it through
+the GitHub Actions below.
+
+## 1. Install
+
+```bash
+uv add --dev "due-work-harness[django]"     # or [celery], [procrastinate], [dbos]; combine as needed
+```
+
+The core needs only pytest and pydantic. An extra adds that framework's integration.
+
+## 2. Configure the scan
+
+```toml
+# pyproject.toml
+[tool.due-work-harness]
+production-packages = ["myapp"]   # the code that must be accounted for
+```
+
+A kind is scanned whenever production code imports its framework, directly or
+through another module of the project, so the result is the same wherever the
+check runs, framework installed or not:
+
+| Kind | A site is |
+| --- | --- |
+| `django` | `transaction.on_commit(...)`, including through `sync_to_async` |
+| `celery` | `.delay(...)` / `.apply_async(...)` and their `_on_commit` variants on a `@shared_task` / `@app.task`, and `send_task(...)` |
+| `procrastinate` | `.defer(...)` / `.defer_async(...)` on an `@app.task`, including after `.configure(...)` |
+| `dbos` | `DBOS.start_workflow(...)`, and `queue.enqueue(workflow, ...)` for a `@DBOS.workflow` |
+| `dramatiq` | `.send(...)` / `.send_with_options(...)` on an `@actor` |
+| `rq` | `enqueue`, `enqueue_call`, `enqueue_at`, `enqueue_in` on `rq`/`django_rq` or a queue they returned; `.delay(...)` on an `@job` |
+| `django-tasks` | `.enqueue(...)` / `.aenqueue(...)` on a `django.tasks` (or `django_tasks`) `@task` |
+
+A site is any reference to the handoff, called or not, through any alias: a
+local name, a parameter default, `self.hook`, a re-export, `sync_to_async(...)`
+or `functools.partial(...)` all count, in the outermost function that contains
+them. `sites = ["celery"]` adds a kind the scan cannot detect (a framework
+reached only through a third-party wrapper); it never removes a detected one.
+A project helper that hands work off for its callers (Zulip's
+`send_event_on_commit`, say) is declared in `bridges` with its own site count, so
+each call to it becomes a site in its caller. `exclude` adds name patterns to
+skip, and may never hide production code. See
+[`coverage/config.py`](src/due_work_harness/coverage/config.py) for every key.
+
+## 3. See what you have, and baseline the past
+
+```bash
+uv run due-work-harness sites      # every site, and its disposition
+uv run due-work-harness baseline   # a [tool.due-work-harness.baseline] table for today's sites
+```
+
+Paste the baseline into `pyproject.toml` to adopt without fixing everything at
+once. The baseline records work that predates adoption and **only shrinks**: in
+CI, `check --base-ref <base>` refuses any entry a change adds.
+
+## 4. Configure the host for your tests
+
+```python
+# conftest.py
+from due_work_harness import configure
+from due_work_harness.integrations.django import django_host
+
+configure(django_host(production_packages={"myapp"}))
+```
+
+The host tells the framework-free proofs what only your framework knows: how
+to reach the database, count commits and freeze time.
+
+If your code publishes through Celery, let crash histories refuse each publish
+as a broker that is down would:
+
+```python
+from due_work_harness.integrations.celery import celery_publication_breaker
+
+configure(django_host(production_packages={"myapp"}, publication_breaker=celery_publication_breaker))
+```
+
+## 5. Give each site a disposition
+
+**Cover it with a contract**: the proofs that it survives lost messages and
+dead workers. Name the exact function the contract insures:
+
+```python
+@due_work_contract_suite(ORDER_NOTIFICATIONS, covers=(DueWorkSource(OrderService.place),))
+class TestOrderNotificationsDueWork:
+    pass
+```
+
+Start small: a `HandoffHistory` with `assert_crash_at_every_commit_converges` is
+often the first proof worth having. See [the README](README.md) and
+[what a green result means](docs/what-a-green-result-means.md).
+
+**Or exempt it, with proof**, when losing the handoff genuinely costs nothing:
+
+```python
+@exempt_due_work_suite(
+    DueWorkSource(summaries.rename_order),
+    reason="the read path rebuilds a summary that disagrees with its order",
+    prove=LossIsAbsorbedElsewhere(strand=..., observe=..., absorb=summaries.summary),
+)
+class TestSummaryEvictionExemption:
+    pass
+```
+
+The proof runs as a test. An exemption without one is refused, and so is a
+proof written in the test itself (a lambda, a local function): it must be a
+harness probe such as `LossIsAbsorbedElsewhere`, whose `absorb` is the
+production path the reason names.
+
+Each call then removes its function from the baseline.
+
+## 6. Enforce it in CI
+
+```yaml
+jobs:
+  due-work-check:
+    # Static: no database, no framework, seconds. Pins the harness version from your uv.lock.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: gigaverse-app/due-work-harness/check@v0
+
+  due-work-suites:
+    # The generated contract, safety and exemption suites, in your own environment.
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env: { POSTGRES_PASSWORD: postgres }
+        ports: ["5432:5432"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: gigaverse-app/due-work-harness/test@v0
+        with:
+          sync-args: --all-extras
+          pytest-args: --ds=myproject.settings
+```
+
+Without GitHub Actions, the same two steps are:
+
+```bash
+uv run due-work-harness check --base-ref origin/main
+uv run pytest -m due_work
+```
+
+Every case the harness generates carries the `due_work` mark, so `-m due_work`
+selects exactly the adoption suites. The `test` action also passes
+`--due-work-verify`, which fails the session unless every declaration the check
+counted ran a case: a suite skipped by an `importorskip`, deselected or never
+collected cannot keep its function accounted for. Add it to the plain command
+too:
+
+```bash
+uv run pytest -m due_work --due-work-verify
+```
+
+A declaration the check counts is one pytest will run as written: a
+module-level `Test*` class, not rebound later in its module, with no skip or
+xfail mark, using the harness's own decorator, `DueWorkSource` and contract.