netprotocols 2.2.1__tar.gz → 2.4.0__tar.gz

netprotocols-2.4.0/.claude/skills/steward/SKILL.md

@@ -0,0 +1,26 @@
+# Steward: driving PRs to green in this repo
+
+Repo-specific guidance for any Claude Code session babysitting, driving-to-green, or otherwise acting on an open pull request in this repository. This takes precedence over generic PR-babysitting conventions on the points below; it does not expand access or let a session skip anything those generic rules mark as "never."
+
+## Independent implementation and review for CI/CodeRabbit-reported bugs
+
+**Rule 1 — independent implementation.** A fix to a bug reported by CI (a failing check, a CodeRabbit finding, a bot review comment) must be implemented by an independent session or sub-agent — never by the same session/agent that authored the code the bug was found in.
+
+**Rule 2 — independent review.** Each such fix, once implemented, must be reviewed by another independent agent before proceeding (pushing, resolving the finding's thread, moving to the next item). This review is a separate pass from whichever agent wrote the fix.
+
+### Why this exists
+
+Observed directly on [PR #158](https://github.com/EONRaider/NETProtocols/pull/158): the same session that authored a refactor (source dedup, test hardening, new CI workflows) also implemented every fix for what CodeRabbit found in that code. This repeated the exact failure mode being fixed at least once — a regression test written to guard `mutation.yml`'s DNS mutation-testing scope checked `pattern in text` against the whole file rather than the actual executed command block, the same "checks vocabulary, not behavior" bug already fixed twice earlier in the same review pass (a `uses:` line-matching regex, and a reproducible-build test that checked for the word "reproducible" rather than an actual hash comparison). The author's own blind spots — the same assumptions and habits that produced the original bug — carried straight into the fix, and an external reviewer had to catch it again on the next round.
+
+An agent fixing its own bug tends to re-apply the same mental model that produced it. A fresh session or sub-agent, with no investment in the original approach, is more likely to notice when a fix is narrower than the problem, or repeats the original mistake in a new shape.
+
+### How to apply this in practice
+
+When a CI check fails or CodeRabbit (or any other bot/reviewer) reports a finding on a PR in this repo:
+
+1. **Diagnose** in the current session — reading the failure, the diff, and the relevant code is fine and doesn't need to be delegated.
+2. **Delegate the fix itself** to an independent sub-agent (e.g. via the Agent tool), giving it the finding and enough context to act, but without it inheriting the current session's authorship of the original code — it should approach the fix fresh, not defend or extend its own prior work.
+3. **Delegate review of that fix** to a second, separate sub-agent before pushing — distinct from the agent that implemented the fix. This agent should verify the fix actually closes the gap (ideally by constructing a case that would have slipped past the old code and confirming the new code catches it, not just that the reported symptom is gone), and check it didn't introduce the same class of bug elsewhere.
+4. Only after both steps pass does the fix get pushed and the finding marked resolved.
+
+This applies to fixes for bugs reported by CI, CodeRabbit, another bot, or a human reviewer — the fix-a-reported-bug loop, where the risk of an author's blind spots recurring is highest. It does not require every commit or every piece of new feature work in this repo to go through this two-step delegation.

netprotocols-2.4.0/.gitattributes

@@ -0,0 +1,3 @@
+# The HTTP fixture streams are wire bytes: their CRLFs are the grammar
+# under test, so no checkout may convert them.
+tests/fixtures/http/* -text

netprotocols-2.4.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @EONRaider

netprotocols-2.4.0/.github/dependabot.yml

@@ -0,0 +1,65 @@
+version: 2
+
+updates:
+  # --- Python tooling, managed by uv --------------------------------
+  #
+  # This project's dependencies are declared exclusively via PEP 735
+  # [dependency-groups] in pyproject.toml (see uv.lock), not the older
+  # [project.optional-dependencies] table. Dependabot's "pip" ecosystem
+  # does not parse [dependency-groups]; only the native "uv" ecosystem
+  # does (GA since March 2025, with dependency-groups parsing landing
+  # in dependabot/dependabot-core#11796), so "uv" is used here rather
+  # than "pip".
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore"
+    groups:
+      # netprotocols ships zero runtime dependencies today, so every
+      # update currently comes from the "dev" dependency-group (pytest,
+      # mypy, ruff, etc.) -- kept current here as its own group rather
+      # than left to open one PR per package. Matched by explicit
+      # package name instead of `dependency-type: development`: as of
+      # this writing Dependabot's dependency-type classifier does not
+      # work correctly for the uv ecosystem and reports every
+      # dependency as "production" regardless of where it's declared
+      # (see dependabot/dependabot-core#13202), which would leave a
+      # `dependency-type: development` group empty -- or, used the
+      # other way around, wrongly sweep this same dev tooling into a
+      # "runtime" group. A future runtime dependency added under
+      # [project.dependencies] is intentionally left out of this list,
+      # so it keeps updating on its own outside this group rather than
+      # being bundled in with dev tooling.
+      dev-dependencies:
+        patterns:
+          - "hypothesis"
+          - "mypy"
+          - "pytest"
+          - "pytest-cov"
+          - "ruff"
+
+  # --- GitHub Actions -------------------------------------------------
+  #
+  # Keeps the SHA-pinned `uses:` references in .github/workflows current
+  # (Dependabot updates both the pinned SHA and its trailing `# vX.Y.Z`
+  # comment).
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "ci"
+    groups:
+      # github/codeql-action ships init, analyze, and upload-sarif as
+      # subdirectories of one repository, but Dependabot tracks each
+      # `uses:` path as its own dependency and opens one PR per path.
+      # init and analyze must run the same release -- analyze refuses a
+      # config file written by a different init version ("Loaded a
+      # configuration file for version '4.37.9', but running version
+      # '4.38.1'") -- so every split PR fails CodeQL on its own and
+      # none can merge. Grouping them bumps all three together.
+      codeql-action:
+        patterns:
+          - "github/codeql-action*"

netprotocols-2.4.0/.github/workflows/ci.yml

@@ -0,0 +1,173 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+  # Callable so the release workflow can run this exact ladder against a
+  # tagged commit before publishing (see release.yml). Keeping one
+  # definition means the release gate cannot drift from the PR gate.
+  workflow_call:
+
+# Cancel a stale run the moment a newer one starts for the same branch
+# or pull request, so a quick follow-up push doesn't leave two ladders
+# racing for runners. Keyed on the PR number when this is a pull_request
+# run and on the ref otherwise. The group name is the literal "ci"
+# prefix, not ${{ github.workflow }}: inside a workflow_call, that
+# expression is the CALLER's workflow name, not this one's. Using it
+# here made this group collide with release.yml's own top-level
+# "Release-<ref>" group on a tag push, and GitHub cancelled the whole
+# run as a self-deadlock.
+concurrency:
+  group: ci-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+# No job here needs to write anything -- lint/typecheck/test/build/pyodide/
+# benchmark all read the checked-out tree and call out to local tools.
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.12"
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.12"
+      - run: uv run mypy
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv run --frozen pytest --cov=netprotocols --cov-report=term
+
+  # Scans the dev dependency group (the only third-party code CI itself
+  # pulls in) for known vulnerabilities. Exported with --no-emit-project
+  # so the audit sees pinned, hashed third-party requirements only --
+  # not an unhashable `-e .` reference to this repo's own in-tree
+  # package, which pip-audit cannot install under --require-hashes
+  # (implied automatically once any requirement carries a hash).
+  dependency-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.12"
+      - name: Export dev dependencies
+        run: >-
+          uv export --group dev --format requirements-txt --no-emit-project
+          -o requirements-dev.txt
+      - name: Audit dev dependencies for known vulnerabilities
+        run: >-
+          uv run --with pip-audit --no-project
+          pip-audit -r requirements-dev.txt
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - run: uv build
+      - run: uv run --isolated --no-project --with dist/*.whl python -c "import netprotocols; print(netprotocols.__version__)"
+      # Builds are supposed to be a pure function of the source tree, so
+      # two runs back-to-back must emit byte-identical wheels. Diffing
+      # their sha256 (rather than the files directly) catches drift
+      # from things like embedded timestamps or non-deterministic
+      # archive member ordering without needing a full binary diff.
+      - name: Verify the wheel build is reproducible
+        run: |
+          set -euo pipefail
+          uv build -o dist-repro-1
+          uv build -o dist-repro-2
+          hash1=$(sha256sum dist-repro-1/*.whl | cut -d ' ' -f1)
+          hash2=$(sha256sum dist-repro-2/*.whl | cut -d ' ' -f1)
+          echo "Build 1 sha256: $hash1"
+          echo "Build 2 sha256: $hash2"
+          if [ "$hash1" != "$hash2" ]; then
+            echo "::error::Wheel build is not reproducible: sha256 differs between two successive 'uv build' runs."
+            exit 1
+          fi
+          echo "Wheel build is reproducible."
+
+  # Proves the README's browser/WASM claim (#99) against the real
+  # thing, not a simulation of it: boots an actual Pyodide runtime
+  # (scripts/pyodide/run_in_pyodide.mjs, via Node — no browser needed,
+  # same WebAssembly build either way) and decodes the whole
+  # real-capture corpus with the wheel this job just built. See
+  # scripts/pyodide/check_in_pyodide.py for what it checks and why.
+  pyodide:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "22"
+      - run: npm ci
+        working-directory: scripts/pyodide
+      - run: >-
+          node scripts/pyodide/run_in_pyodide.mjs
+          "$GITHUB_WORKSPACE" scripts/pyodide/check_in_pyodide.py
+
+  # Blocking, at 15% below the committed baseline. The threshold has
+  # runner data behind it: this job's first run measured 3.7% away from
+  # a baseline recorded on entirely different hardware, and run-to-run
+  # spread on one machine is ~2%. 15% is therefore roughly four times
+  # the noise it has to tolerate, which leaves real regressions (Tier 1
+  # moved this number by 30-90% a step) nowhere to hide.
+  #
+  # A failure re-measures once before failing, because a shared runner
+  # can lose a slice of CPU to a neighbour: a genuine regression fails
+  # both attempts, a noisy one usually does not.
+  #
+  # Pinned to the baseline's interpreter on purpose: normalization
+  # cancels how fast the machine is, not which CPython it runs (see the
+  # module docstring in scripts/benchmark.py). If a change is a
+  # deliberate trade, re-record with --update-baseline and say why.
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.12"
+      - name: Corpus decode throughput
+        shell: bash
+        run: |
+          # Keep the benchmark's own exit status: piping the whole thing
+          # into tee would report tee's, and wrapping it in a { } group
+          # would report the trailing echo's -- either way the gate
+          # would pass while the check failed.
+          status=0
+          uv run --frozen --group bench python scripts/benchmark.py \
+            --check --threshold 15 --compare >benchmark.out 2>&1 || status=$?
+          {
+            echo '```'
+            cat benchmark.out
+            echo '```'
+          } >>"$GITHUB_STEP_SUMMARY"
+          cat benchmark.out
+          exit "$status"

netprotocols-2.4.0/.github/workflows/codeql.yml

@@ -0,0 +1,50 @@
+name: CodeQL
+
+# Advanced-setup workflow (a checked-in file) rather than GitHub's
+# built-in "default setup", so this analysis lives in version control
+# alongside the rest of this repository's CI (ci.yml, fuzz.yml,
+# release.yml, mutation.yml, scorecard.yml) and its action pins are
+# reviewable the same way theirs are. Default setup is configured
+# through repository settings instead of a file, so it isn't available
+# to author from here.
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+  schedule:
+    # Arbitrary; weekly on Sundays, clear of fuzz.yml's and mutation.yml's
+    # daily 03:00/04:00 UTC slots and scorecard.yml's own Sunday 05:00
+    # UTC slot.
+    - cron: "0 6 * * 0"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  analyze:
+    name: Analyze (python)
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      # Python is interpreted, so there is nothing for autobuild (or a
+      # manual build step) to do: build-mode: none has CodeQL extract
+      # the database straight from source instead. This is the build
+      # mode the CodeQL Action's own docs recommend for interpreted
+      # languages, and it sidesteps the question of an autobuild step
+      # fitting this project's uv-based build at all.
+      - uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+        with:
+          languages: python
+          build-mode: none
+
+      - uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2

netprotocols-2.4.0/.github/workflows/docs-lint.yml

@@ -0,0 +1,75 @@
+name: Docs lint
+
+# Runs lycheeverse/lychee (a link checker) over the small set of
+# hand-maintained docs that carry the project's external claims and
+# cross-references: README.md, ARCHITECTURE.md, CONTRIBUTING.md,
+# CHANGELOG.md, and docs/CLAIMS.md. Two triggers, for two different
+# failure modes: the pull_request path filter catches a broken link
+# introduced *by* a docs edit, and the weekly schedule catches a link
+# that was fine when written but has since gone dead out from under an
+# otherwise-unchanged file (a renamed issue, a retired badge service, a
+# moved external page) -- which no docs PR would ever surface.
+on:
+  pull_request:
+    branches: [master]
+    paths:
+      - "README.md"
+      - "ARCHITECTURE.md"
+      - "CONTRIBUTING.md"
+      - "CHANGELOG.md"
+      - "docs/CLAIMS.md"
+  schedule:
+    # Arbitrary; weekly on Mondays, clear of fuzz.yml's/mutation.yml's
+    # daily 03:00/04:00 UTC slots and scorecard.yml's Sunday 05:00 slot.
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lychee:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      # lychee-action's `token` input defaults to `${{ github.token }}`,
+      # which it exports as GITHUB_TOKEN; lychee reads that itself to
+      # check github.com links through the API instead of scraping the
+      # page. That's what keeps the ~15 github.com/EONRaider/NETProtocols
+      # issue/release links in these docs from tripping an anonymous
+      # rate limit -- most relevant on the weekly schedule run, which
+      # has no pull request author's own browsing to blend in with.
+      #
+      # --timeout/--max-retries/--retry-wait-time are more generous
+      # than lychee's own defaults (20s/3/1s) to absorb a slow or
+      # momentarily rate-limited external host without failing the
+      # build outright.
+      #
+      # --exclude covers img.shields.io, which serves this project's
+      # three static README badges: a shared, heavily-trafficked CDN
+      # known to intermittently rate-limit or time out under bulk/CI
+      # traffic across many unrelated repos, independent of whether
+      # any given badge URL is actually broken. Every other file was
+      # checked by hand for placeholder/example domains (example.com,
+      # localhost, and the like) before this workflow was added; none
+      # were found, so no other entries are excluded here.
+      - name: Check links in the project's hand-maintained docs
+        uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2.9.0
+        with:
+          args: >-
+            --no-progress
+            --verbose
+            --timeout 30
+            --max-retries 3
+            --retry-wait-time 10
+            --exclude '^https://img\.shields\.io'
+            README.md
+            ARCHITECTURE.md
+            CONTRIBUTING.md
+            CHANGELOG.md
+            docs/CLAIMS.md

{netprotocols-2.2.1 → netprotocols-2.4.0}/.github/workflows/fuzz.yml

@@ -12,6 +12,14 @@ on:
     - cron: "0 3 * * *"
   workflow_dispatch:
 
+# Keyed on the triggering event too, so the nightly cron can never
+# cancel a manually dispatched run on the same ref (the release
+# checklist in CONTRIBUTING.md relies on one) -- runs of the same kind
+# still supersede each other.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}
+  cancel-in-progress: true
+
 permissions:
   contents: read
 
@@ -29,8 +37,8 @@ jobs:
   fuzz:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
-      - uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           python-version: "3.12"
       # Keyed by run id with a prefix restore-key: a fixed key would
@@ -40,7 +48,7 @@ jobs:
       # today's as a new entry, so Hypothesis's example database grows
       # night over night instead of starting cold every time.
       - name: Restore accumulated Hypothesis examples
-        uses: actions/cache@v4
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: .hypothesis
           key: hypothesis-nightly-${{ github.run_id }}
@@ -57,8 +65,41 @@ jobs:
       # repo write access to re-run the job locally.
       - name: Upload the failing example database
         if: failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: hypothesis-nightly-failure-${{ github.run_id }}
           path: .hypothesis
           retention-days: 30
+
+  # Coverage-guided fuzzing of the same target, via Atheris rather than
+  # Hypothesis's example strategies above -- it drives decode_frame with
+  # libFuzzer's mutation engine instead of Hypothesis's, so it explores
+  # a different part of the input space. HTTP.decode gets a harness of
+  # its own because decode_frame never reaches it: HTTP is not
+  # port-dispatched. Pinned to Python 3.12 only,
+  # like the "fuzz" job above: Atheris hooks CPython internals directly
+  # and tends to lag new interpreter releases, so it isn't given the
+  # full 3.12/3.13/3.14 matrix the compatibility-gate "test" job in
+  # ci.yml runs.
+  atheris:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.12"
+      - name: Run Atheris against decode_frame
+        run: |
+          uv run --frozen --with atheris \
+            python tests/fuzz/fuzz_decode_frame.py -max_total_time=300
+      - name: Run Atheris against HTTP.decode
+        run: |
+          uv run --frozen --with atheris \
+            python tests/fuzz/fuzz_http_decode.py -max_total_time=300
+      - name: Upload crash artifacts
+        if: failure()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: atheris-crash-${{ github.run_id }}
+          path: crash-*
+          retention-days: 30

netprotocols-2.4.0/.github/workflows/mutation.yml

@@ -0,0 +1,115 @@
+name: Nightly mutation testing
+
+# Separate from ci.yml on purpose, same reasoning as fuzz.yml: ci.yml is
+# reused via workflow_call by release.yml, so folding a schedule trigger
+# into it would fire mutation testing on every release too, not just
+# once a night.
+on:
+  schedule:
+    # Arbitrary; offset an hour past fuzz.yml's 03:00 UTC slot so the
+    # two nightly jobs don't contend for the same runner pool.
+    - cron: "0 4 * * *"
+  workflow_dispatch:
+
+# Keyed on the triggering event too, so the nightly cron can never
+# cancel a manually dispatched run on the same ref (the release
+# checklist in CONTRIBUTING.md relies on one) -- runs of the same kind
+# still supersede each other.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  # Mutation testing itself is exploratory/maintenance, not a
+  # compatibility gate, so this is pinned to one interpreter — same
+  # reasoning as fuzz.yml's "fuzz" job.
+  mutation:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.12"
+      # mutmut hashes each mutated file plus the tests that cover it and
+      # skips re-running mutants whose inputs haven't changed since the
+      # last recorded result, so carrying its cache forward night over
+      # night saves real work — same accumulation pattern as fuzz.yml's
+      # Hypothesis example database. Keyed by run id with a prefix
+      # restore-key for the same reason: a fixed key would restore
+      # forever but never save a new entry.
+      - name: Restore accumulated mutmut cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: |
+            .mutmut-cache
+            mutants
+          key: mutmut-nightly-${{ github.run_id }}
+          restore-keys: |
+            mutmut-nightly-
+      # The restored cache also carries mutants/mutmut-stats.json, the
+      # map from each function to the tests that call it. When that map
+      # exists, mutmut 3.8 re-traces only tests it has never seen, so a
+      # function added since the cached run (a new helper called only
+      # by existing tests) maps to no tests and every one of its
+      # mutants reads "no tests"; so does an existing test edited to
+      # call a function it didn't before. Without the map, mutmut
+      # traces the configured test selection in full, which costs one
+      # traced pytest pass. Nothing else is lost: with the positional
+      # filters below, mutmut re-runs every in-scope mutant regardless
+      # of a cached result.
+      - name: Drop the cached function-to-test map
+        run: rm -f mutants/mutmut-stats.json
+      - name: Install the project with dev dependencies
+        run: uv sync --group dev --frozen
+      # File-level scope (src/netprotocols/checksum.py, _tlv.py,
+      # layer7/dns.py and layer7/http.py) comes from the project's mutmut config (pyproject.toml's
+      # [tool.mutmut] table) via only_mutate, not hardcoded here.
+      # dns.py's in-scope surface is narrower still -- only the
+      # name-compression byte walk, not the record/RDATA/dataclass code
+      # the rest of the file holds -- and mutmut has no config-level way
+      # to express that, so these positional filters (kept in lockstep
+      # with the ones documented next to only_mutate in pyproject.toml)
+      # are what actually narrow it; a filter added or renamed there
+      # without a matching update here is exactly the kind of drift this
+      # comment can't prevent on its own.
+      - name: Run mutmut against the scoped targets
+        run: |
+          uv run --frozen mutmut run \
+            'netprotocols.checksum.*' \
+            'netprotocols._tlv.*' \
+            'netprotocols.layer7.dns.x__read_name*' \
+            'netprotocols.layer7.dns.x__labels*' \
+            'netprotocols.layer7.http.x__*'
+      # `mutmut run` exits 0 however many mutants survive, so it can
+      # never turn this job red on its own. This step is what does: it
+      # fails on any undetected mutant not in the triage record
+      # (scripts/mutmut_survivors.txt), on a stale entry there, and on
+      # a scoped file with no checked mutant at all.
+      - name: Fail on survivors outside the triage record
+        run: |
+          uv run --frozen mutmut results --all true > mutmut-results.txt
+          uv run --frozen python scripts/check_mutmut_survivors.py \
+            mutmut-results.txt
+      # A failed scheduled run already notifies repo watchers by
+      # default (GitHub's standard behavior), and with the step above a
+      # red run means an untriaged survivor or a broken run; nothing
+      # here files an issue on top of it. This makes the results
+      # recoverable without needing repo write access to re-run mutmut
+      # locally. Covers the status listing plus both the sqlite-file
+      # cache and the mutated-copies directory, since either of the
+      # latter may be what a given mutmut version writes; whatever
+      # doesn't exist is silently skipped.
+      - name: Upload mutmut results on failure
+        if: failure()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: mutmut-nightly-failure-${{ github.run_id }}
+          path: |
+            mutmut-results.txt
+            .mutmut-cache
+            mutants
+          if-no-files-found: ignore
+          retention-days: 30

netprotocols-2.4.0/.github/workflows/pr-title-lint.yml

@@ -0,0 +1,33 @@
+name: PR Title Lint
+
+# Enforces Conventional Commits shape (https://www.conventionalcommits.org/)
+# on the *pull request title* only — e.g. `feat: ...`, `fix: ...`,
+# `docs: ...`, `chore: ...`. This is unrelated to this repo's guidance on
+# individual commit messages within a PR (see CONTRIBUTING.md); nothing
+# here checks or rewrites those.
+#
+# Runs on `pull_request` (not `pull_request_target`) so it only ever sees
+# the PR's own metadata with a read-only, non-elevated token — no need for
+# the elevated-permissions trigger the action's own docs suggest for
+# repos that also want its optional "[WIP]" title support, which this
+# repo doesn't use.
+on:
+  pull_request:
+    branches: [master]
+    types: [opened, edited, synchronize]
+
+permissions:
+  pull-requests: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  lint-pr-title:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}