deliverability-guard 0.1.0__tar.gz

deliverability_guard-0.1.0/.editorconfig

@@ -0,0 +1,21 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.py]
+indent_size = 4
+
+[*.{yml,yaml,json,toml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

deliverability_guard-0.1.0/.env.example

@@ -0,0 +1,5 @@
+# Copy to .env and fill in. Never commit .env — it is gitignored.
+#
+# Instantly v2 API key. Needs scopes: accounts:update, accounts:all
+# (or all:update / all:all). See https://developer.instantly.ai
+INSTANTLY_API_KEY=

deliverability_guard-0.1.0/.gitattributes

@@ -0,0 +1,8 @@
+* text=auto eol=lf
+
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary

deliverability_guard-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,58 @@
+name: Bug report
+description: Something is broken or behaving incorrectly.
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug, including what you expected instead.
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: How to reproduce
+      description: Minimal steps to reproduce, ideally including your `thresholds.yml` (redact anything sensitive) and whether `dry_run` was on.
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: deliverability-guard version
+      placeholder: e.g. 0.1.0
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: e.g. 3.12.4
+    validations:
+      required: true
+
+  - type: dropdown
+    id: provider
+    attributes:
+      label: Provider(s) involved, if relevant
+      multiple: true
+      options:
+        - Instantly
+        - Smartlead
+        - Google Postmaster Tools
+        - Not provider-specific
+        - Other (mention in description)
+    validations:
+      required: false
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant decision log / traceback
+      description: Paste the relevant excerpt from `audit/log.py` output or a stack trace. This will be rendered as a code block — do not paste real API keys or PII.
+      render: shell
+    validations:
+      required: false

deliverability_guard-0.1.0/.github/ISSUE_TEMPLATE/config.yml

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

deliverability_guard-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,29 @@
+name: Feature request
+description: Propose something new — a provider driver, a signal, a capability.
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: What can't you do today that this would enable? Prefer a concrete scenario over an abstract capability.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed approach
+      description: If you have one. It's fine to leave this blank and just describe the problem.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I checked BUILD-PLAN.md to see if this is already scoped for a future version, deferred, or explicitly a non-goal.
+          required: true
+        - label: If this involves a new provider or external API, I've noted what's verified vs. assumed about its behavior.
+          required: false

deliverability_guard-0.1.0/.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+    cooldown:
+      default-days: 7
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+    cooldown:
+      default-days: 7

deliverability_guard-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,25 @@
+## What and why
+
+<!-- What does this change, and what problem does it solve? -->
+
+## AI disclosure
+
+<!-- Required. See CONTRIBUTING.md § Use of AI. -->
+
+- AI-assisted: <!-- yes/no -->
+- Model / harness: <!-- e.g. Claude Sonnet 5 via Claude Code -->
+- What was and wasn't AI-generated:
+
+## New dependencies
+
+<!-- One line of justification per new dependency, or "None". -->
+
+## Checklist
+
+- [ ] `uv run ruff check . && uv run ruff format --check . && uv run pyright && uv run pytest` passes locally
+- [ ] `CHANGELOG.md` has an entry under `## Unreleased`
+- [ ] New behavior has a test, or this PR explains why not
+- [ ] An ADR is included if this decision is expensive to reverse
+- [ ] No code path can pause/throttle a real mailbox without explicit `dry_run=False`
+- [ ] No missing/absent data is coerced to zero anywhere in this change
+- [ ] I reviewed the full diff myself before opening this PR

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

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  # A real Python version matrix. This was a single job while the repo was
+  # private, since Actions minutes are metered there; the repo is public
+  # now, so there's real value in catching a version-specific regression
+  # instead of only ever testing 3.12. See docs/plans/going-public-checklist.md.
+  check:
+    name: lint, format, types, tests
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --locked --all-groups
+
+      - name: Ruff check
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Pyright
+        run: uv run pyright
+
+      - name: Pytest
+        run: uv run pytest

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

@@ -0,0 +1,133 @@
+name: Release
+
+# Tag-triggered, on the parsedmarc pattern: verify the tag matches the
+# package version -> verify CHANGELOG.md has a section for it -> run the
+# full CI suite -> build -> publish to PyPI via Trusted Publishing (OIDC,
+# no API token secret anywhere) into an environment that requires manual
+# approval -> create the GitHub Release from the CHANGELOG section.
+#
+# Set up the PyPI Trusted Publisher BEFORE pushing the first tag -- PyPI
+# needs to already trust this repo/workflow/environment combination, or the
+# publish step has nothing to authenticate against.
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: verify tag matches version, CHANGELOG has a section
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          # This workflow publishes release artifacts; a cache poisoned by
+          # an earlier run must never be trusted here, so caching is off
+          # for this workflow specifically (unlike ci.yml, which runs far
+          # more often and has more to gain from it).
+          enable-cache: false
+
+      - name: Verify tag matches package version
+        run: |
+          tag_version="${GITHUB_REF_NAME#v}"
+          pkg_version="$(uvx hatch version)"
+          if [ "$tag_version" != "$pkg_version" ]; then
+            echo "::error::tag $GITHUB_REF_NAME (version $tag_version) does not match" \
+                 "package version $pkg_version (src/deliverability_guard/__init__.py)"
+            exit 1
+          fi
+          echo "OK: tag $GITHUB_REF_NAME matches package version $pkg_version"
+
+      - name: Verify CHANGELOG.md has a section for this version
+        run: |
+          pkg_version="$(uvx hatch version)"
+          if ! grep -qE "^## \[?${pkg_version//./\\.}\]?" CHANGELOG.md; then
+            echo "::error::CHANGELOG.md has no '## $pkg_version' section"
+            exit 1
+          fi
+          echo "OK: CHANGELOG.md has a section for $pkg_version"
+
+  ci:
+    name: run CI
+    needs: verify
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    name: build sdist and wheel
+    needs: ci
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: false # see the same note in the verify job above
+
+      - name: Build
+        run: uv build
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://pypi.org/project/deliverability-guard/
+    permissions:
+      id-token: write # required for PyPI Trusted Publishing (OIDC); no API token anywhere
+      contents: read
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      # PEP 740 attestations are generated and uploaded automatically here
+      # under Trusted Publishing -- no extra configuration -- and show up
+      # as a provenance badge on the PyPI project page.
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  github-release:
+    name: create GitHub Release
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Extract this version's CHANGELOG section
+        run: |
+          pkg_version="$(sed -n 's/^__version__ = "\(.*\)"/\1/p' src/deliverability_guard/__init__.py)"
+          awk -v ver="$pkg_version" '
+            $0 ~ "^## \\[?" ver { found=1; next }
+            found && /^## / { exit }
+            found { print }
+          ' CHANGELOG.md > release-notes.md
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file release-notes.md

deliverability_guard-0.1.0/.github/workflows/zizmor.yml

@@ -0,0 +1,39 @@
+name: zizmor
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  zizmor:
+    name: zizmor GitHub Actions security audit
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+      actions: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+
+      - name: Run zizmor
+        run: uvx zizmor --format sarif . > results.sarif
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload SARIF file
+        # Code scanning (and therefore SARIF upload) requires GitHub Advanced
+        # Security, which is not enabled by default on a private repo. This
+        # step will start succeeding once code scanning is turned on at
+        # go-public time (docs/plans/going-public-checklist.md) — until then,
+        # don't let an environment limitation fail CI on every push.
+        continue-on-error: true
+        uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
+        with:
+          sarif_file: results.sarif
+          category: zizmor

deliverability_guard-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Secrets — never commit
+.env
+*.sqlite
+*.sqlite3
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.hypothesis/
+
+# Type checkers
+.mypy_cache/
+.pyright/
+.pytype/
+
+# Tooling
+.ruff_cache/
+
+# Editors / OS
+.DS_Store
+.idea/
+*.swp

deliverability_guard-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+# Fast, local checks only. Types (pyright) and tests (pytest) run in CI, not
+# here — a slow pre-commit gets disabled. See AGENTS.md.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.5
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml

deliverability_guard-0.1.0/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["charliermarsh.ruff"]
+}

deliverability_guard-0.1.0/AGENTS.md

@@ -0,0 +1,67 @@
+# AGENTS.md
+
+## Stop and read this before you write code
+
+This repo has conventions. Violating them wastes a review cycle.
+
+## Commands
+
+- Install: `uv sync`
+- Test: `uv run pytest`
+- Lint: `uv run ruff check . && uv run ruff format --check .`
+- Types: `uv run pyright`
+- All of it: `uv run ruff check . && uv run ruff format --check . && uv run pyright && uv run pytest`
+
+## Layout
+
+- `src/deliverability_guard/` — the package. `tests/` mirrors it. Never put tests inside the package.
+- `docs/decisions/` — ADRs (MADR 4). Permanent, numbered, never renumbered.
+- `docs/plans/` — dated design plans. Disposable once executed.
+- `config/thresholds.example.yml` — the default ladder. Copy to `thresholds.yml` to use.
+
+## Non-negotiable
+
+1. **Never commit directly to `main`.** Branch, commit, open a PR. Even for a typo.
+2. **Tests before implementation.** If you are adding behavior, the failing test comes first.
+3. **No secrets in the repo, ever** — not in tests, not in fixtures, not in examples. Use env vars and `.env.example`.
+4. **Never re-type a file's contents from tool output.** Output can be truncated. Edit in place.
+5. **Every dependency added needs a one-line justification in the PR body.**
+6. **If a decision is expensive to reverse, write an ADR in the same PR.**
+7. **Linter versions are pinned exactly.** Do not float them to fix a failure — fix the code, or bump deliberately in its own PR.
+
+## Project-specific non-negotiables
+
+1. **DRY RUN IS THE DEFAULT.** Any code path that can pause or throttle a real
+   mailbox must be off unless explicitly enabled. A tool that stops someone's
+   revenue by accident is worse than no tool. Dry-run must produce decisions
+   identical to the live path — implement it as a no-op provider decorator,
+   never as a separate logic branch.
+2. **NEVER coerce missing data to zero.** Absence of complaint data is
+   `INSUFFICIENT_DATA`, never `OK`. This is the bug that makes monitoring go
+   dark exactly when things are worst — a throttled domain sends less, can
+   drop below a provider's privacy threshold, and disappear from reporting
+   entirely.
+3. **Never claim a statistical property the data cannot support.** Under
+   roughly 1,000 sends/day/provider this is a leading-indicator monitor, not a
+   statistically valid complaint-rate breaker. Say so in the README and never
+   soften it.
+4. **No live API calls in tests.** Recorded fixtures only.
+
+## Before opening a PR
+
+- [ ] The full check command above passes locally
+- [ ] `CHANGELOG.md` has an entry under `## Unreleased`
+- [ ] No new file lacks a test, or the PR says why
+- [ ] The PR body discloses: model, harness, and that it was AI-assisted
+- [ ] You showed the human the full diff and got approval
+
+## What gets rejected
+
+- Direct commits to `main`
+- Reformatting unrelated code
+- New dependencies without justification
+- "Improvements" nobody asked for, bundled into an unrelated PR
+- Removing a test to make CI pass
+- Anything that makes an approval gate optional
+- A breaker/provider code path that can act (pause/throttle) without an explicit `dry_run=False`
+- Code that treats missing data as zero, anywhere in the pipeline