nnrp-py 1.0.0rc2__tar.gz

nnrp_py-1.0.0rc2/.editorconfig

@@ -0,0 +1,14 @@
+root = true
+
+[*.py]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+
+[*.md]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = false

nnrp_py-1.0.0rc2/.github/PULL_REQUEST_TEMPLATE/bugfix.md

@@ -0,0 +1,38 @@
+## Bug
+
+- What was broken?
+- How could the issue be reproduced?
+
+## Root Cause
+
+- What actually caused the issue?
+
+## Fix
+
+- What changed to fix it?
+- What regression risk remains?
+
+## Validation
+
+- [ ] `ruff check .`
+- [ ] `pytest -q`
+- [ ] Regression test added or existing failure reproduced
+
+Commands or workflow runs used:
+
+```text
+
+```
+
+## Release Impact
+
+- [ ] No package output change
+- [ ] Wheel or sdist contents changed
+- [ ] Release workflow behavior changed
+
+## Checklist
+
+- [ ] Branch name matches repository conventions
+- [ ] Commit messages follow Conventional Commits
+- [ ] PR is squashed to one commit unless this is necessary `release/<version>` branch work
+- [ ] User-facing behavior changes are documented

nnrp_py-1.0.0rc2/.github/PULL_REQUEST_TEMPLATE/docs.md

@@ -0,0 +1,28 @@
+## Summary
+
+- What documentation changed?
+- Who is the primary audience?
+
+## Scope
+
+- Files or sections updated:
+- Any intentionally deferred follow-up:
+
+## Validation
+
+- [ ] Links and paths were checked
+- [ ] Examples or commands were updated if needed
+- [ ] Documentation stays consistent with current package and workflow behavior
+
+Notes:
+
+```text
+
+```
+
+## Checklist
+
+- [ ] Branch name matches repository conventions
+- [ ] Commit messages follow Conventional Commits
+- [ ] PR is squashed to one commit unless this is necessary `release/<version>` branch work
+- [ ] No hidden product or workflow behavior changes were introduced

nnrp_py-1.0.0rc2/.github/PULL_REQUEST_TEMPLATE/feature.md

@@ -0,0 +1,35 @@
+## Summary
+
+- What capability does this PR add?
+- Why is it needed now?
+
+## Implementation
+
+- Main modules or flows changed:
+- Any protocol, runtime, or packaging assumptions introduced:
+- Follow-up work, if any:
+
+## Validation
+
+- [ ] `ruff check .`
+- [ ] `pytest -q`
+- [ ] Build or packaging checked if distribution output changed
+
+Commands or workflow runs used:
+
+```text
+
+```
+
+## Release Impact
+
+- [ ] No package output change
+- [ ] Wheel or sdist contents changed
+- [ ] Release workflow behavior changed
+
+## Checklist
+
+- [ ] Branch name matches repository conventions
+- [ ] Commit messages follow Conventional Commits
+- [ ] PR is squashed to one commit unless this is necessary `release/<version>` branch work
+- [ ] Documentation was updated when behavior changed

nnrp_py-1.0.0rc2/.github/PULL_REQUEST_TEMPLATE/maintenance.md

@@ -0,0 +1,36 @@
+## Summary
+
+- What maintenance change is included?
+- Why is it being made now?
+
+## Change Type
+
+- [ ] CI or workflow change
+- [ ] Tooling or dependency maintenance
+- [ ] Packaging metadata update
+- [ ] Refactor with no intended behavior change
+
+## Validation
+
+- [ ] `ruff check .`
+- [ ] `pytest -q`
+- [ ] Targeted validation for the affected tooling or workflow path
+
+Commands or workflow runs used:
+
+```text
+
+```
+
+## Release Impact
+
+- [ ] No package output change
+- [ ] Wheel or sdist contents changed
+- [ ] Release workflow behavior changed
+
+## Checklist
+
+- [ ] Branch name matches repository conventions
+- [ ] Commit messages follow Conventional Commits
+- [ ] PR is squashed to one commit unless this is necessary `release/<version>` branch work
+- [ ] Follow-up operational work is documented if needed

nnrp_py-1.0.0rc2/.github/PULL_REQUEST_TEMPLATE/release.md

@@ -0,0 +1,44 @@
+## Summary
+
+- What release or release-preparation change is included?
+
+## Versioning
+
+- Target version:
+- Why this version is needed:
+
+## Package Impact
+
+- [ ] Wheel metadata changed
+- [ ] Sdist contents changed
+- [ ] Release workflow behavior changed
+
+Describe the release-facing impact:
+
+## Validation
+
+- [ ] `ruff check .`
+- [ ] `pytest -q`
+- [ ] `python -m build`
+- [ ] Release workflow assumptions were checked
+
+Commands or workflow runs used:
+
+```text
+
+```
+
+## Manual Registry Steps
+
+- [ ] No manual registry work required
+- [ ] PyPI or TestPyPI state was reviewed
+- [ ] GitHub Release asset expectations were reviewed
+
+Notes:
+
+## Checklist
+
+- [ ] Branch name matches repository conventions
+- [ ] Commit messages follow Conventional Commits
+- [ ] PR is squashed to one commit unless this is necessary `release/<version>` branch work
+- [ ] Release notes or docs were updated if needed

nnrp_py-1.0.0rc2/.github/pull_request_template.md

@@ -0,0 +1,41 @@
+## Summary
+
+- PR type: feature / bugfix / docs / maintenance / release
+- What changed?
+- Why is it needed now?
+
+## Implementation
+
+- Main modules or flows changed:
+- Any protocol, runtime, or packaging assumptions introduced:
+- Follow-up work, if any:
+
+## Validation
+
+- [ ] `ruff check .`
+- [ ] `pytest -q`
+- [ ] Build or packaging checked if distribution output changed
+
+Commands or workflow runs used:
+
+```text
+
+```
+
+## Release Impact
+
+- [ ] No package output change
+- [ ] Wheel or sdist contents changed
+- [ ] Release workflow behavior changed
+
+## Checklist
+
+- [ ] Branch name matches repository conventions
+- [ ] Commit messages follow Conventional Commits
+- [ ] PR is squashed to one commit unless this is necessary `release/<version>` branch work
+- [ ] Documentation was updated when behavior changed
+
+## Notes
+
+- Specialized reference templates still live in `.github/PULL_REQUEST_TEMPLATE/`.
+- GitHub does not show an automatic chooser for those files on the standard PR page, so this file acts as the default template.

nnrp_py-1.0.0rc2/.github/workflows/ci.yml

@@ -0,0 +1,104 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  commit-policy:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Enforce single-commit PR policy
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          head_ref="${{ github.head_ref }}"
+          base_ref="${{ github.base_ref }}"
+
+          if [[ "$head_ref" =~ ^release/ ]] || [[ "$base_ref" =~ ^release/ ]]; then
+            echo "Release/version branch PR detected; multi-commit history is allowed when needed."
+            exit 0
+          fi
+
+          commit_count='${{ github.event.pull_request.commits }}'
+          if [ "$commit_count" -ne 1 ]; then
+            echo "Normal PRs from feature/fix/docs/chore branches must contain exactly one commit before review. Current PR has $commit_count commits. Squash the history before requesting review."
+            exit 1
+          fi
+
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[dev] build
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Test with coverage
+        run: >-
+          pytest
+          --cov=src/nnrp
+          --cov=scripts
+          --cov-report=xml:artifacts/coverage/coverage.xml
+          --cov-fail-under=90
+          -q
+
+      - name: Incremental line coverage gate
+        if: github.event_name == 'pull_request' || github.event_name == 'push'
+        shell: bash
+        run: |
+          base_sha=""
+          head_sha=""
+
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            base_sha="${{ github.event.pull_request.base.sha }}"
+            head_sha="${{ github.event.pull_request.head.sha }}"
+          else
+            base_sha="${{ github.event.before }}"
+            head_sha="${{ github.sha }}"
+          fi
+
+          python scripts/check_incremental_coverage.py \
+            --base-sha "$base_sha" \
+            --head-sha "$head_sha" \
+            --threshold 90 \
+            --coverage-xml artifacts/coverage/coverage.xml
+
+  required-checks:
+    needs:
+      - commit-policy
+      - test
+    if: always()
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Enforce required CI path
+        shell: bash
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ] && [ "${{ needs.commit-policy.result }}" != "success" ]; then
+            echo "PR commit policy validation failed."
+            exit 1
+          fi
+
+          if [ "${{ needs.test.result }}" != "success" ]; then
+            echo "Lint, test, total coverage, or incremental coverage validation failed."
+            exit 1
+          fi

nnrp_py-1.0.0rc2/.github/workflows/release.yml

@@ -0,0 +1,139 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: Git ref to release when running manually
+        required: true
+        default: main
+      publish_github_release:
+        description: Publish or update the GitHub Release
+        required: true
+        type: boolean
+        default: true
+      publish_to_pypi:
+        description: Publish built distributions to PyPI
+        required: true
+        type: boolean
+        default: false
+
+permissions:
+  contents: write
+
+jobs:
+  package:
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+    permissions:
+      contents: write
+      id-token: write
+    env:
+      PYPI_PUBLISH_MODE: ${{ vars.PYPI_PUBLISH_MODE || 'disabled' }}
+      PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || github.ref }}
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Resolve version
+        id: version
+        run: |
+          python scripts/resolve_version.py show --github-output --run-number ""
+
+      - name: Validate pushed tag
+        if: github.event_name == 'push'
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          expected_tag="${{ steps.version.outputs.tag_name }}"
+          actual_tag="${{ github.ref_name }}"
+
+          if [ "$actual_tag" != "$expected_tag" ]; then
+            echo "Release tag mismatch: expected $expected_tag but workflow was triggered by $actual_tag."
+            exit 1
+          fi
+
+      - name: Create git tag
+        if: github.event_name == 'workflow_dispatch'
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          git fetch --tags
+          tag="${{ steps.version.outputs.tag_name }}"
+          if [ -z "$(git tag --list "$tag")" ]; then
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git tag "$tag"
+            git push origin "$tag"
+          fi
+
+      - name: Apply build version
+        run: |
+          python scripts/resolve_version.py apply --package-version "${{ steps.version.outputs.package_version }}"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[dev] build twine
+
+      - name: Test
+        run: pytest -q
+
+      - name: Build distribution
+        run: python -m build
+
+      - name: Bundle release artifacts
+        run: |
+          python - <<'PY'
+          import pathlib
+          import zipfile
+
+          version = '${{ steps.version.outputs.package_version }}'
+          artifact_dir = pathlib.Path('artifacts')
+          artifact_dir.mkdir(exist_ok=True)
+          artifact = artifact_dir / f'nnrp-py-{version}.zip'
+          with zipfile.ZipFile(artifact, 'w', compression=zipfile.ZIP_DEFLATED) as archive:
+              for item in sorted(pathlib.Path('dist').glob('*')):
+                  archive.write(item, item.name)
+          PY
+
+      - name: Upload workflow artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: nnrp-py-release-${{ steps.version.outputs.package_version }}
+          path: artifacts/nnrp-py-${{ steps.version.outputs.package_version }}.zip
+          if-no-files-found: error
+          retention-days: 14
+
+      - name: Publish GitHub release
+        if: github.event_name == 'push' || inputs.publish_github_release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.version.outputs.tag_name }}
+          name: ${{ steps.version.outputs.release_name }}
+          files: artifacts/nnrp-py-${{ steps.version.outputs.package_version }}.zip
+
+      - name: Publish to PyPI with Trusted Publisher
+        if: (github.event_name == 'push' || inputs.publish_to_pypi) && env.PYPI_PUBLISH_MODE == 'trusted'
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Publish to PyPI with API token
+        if: (github.event_name == 'push' || inputs.publish_to_pypi) && env.PYPI_PUBLISH_MODE == 'token' && env.PYPI_API_TOKEN != ''
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ env.PYPI_API_TOKEN }}

nnrp_py-1.0.0rc2/.gitignore

@@ -0,0 +1,30 @@
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+.coverage
+.coverage.*
+artifacts/coverage/
+.hypothesis/
+.mypy_cache/
+.nox/
+.pytest_cache/
+.ruff_cache/
+.tox/
+.venv/
+venv/
+build/
+dist/
+htmlcov/
+pip-wheel-metadata/
+site/
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+*.pyc

nnrp_py-1.0.0rc2/CONTRIBUTING.md

@@ -0,0 +1,108 @@
+# Contributing to nnrp-py
+
+This repository publishes Python SDK packages and protocol tooling, so contribution flow needs to stay predictable.
+
+## Branch Strategy
+
+The protected integration branch should be the repository default branch.
+
+For the public GitHub repository, use `main` as the protected integration branch.
+
+Use short-lived topic branches for day-to-day work:
+
+- `feature/<scope>-<topic>` for new capabilities
+- `fix/<scope>-<topic>` for bug fixes
+- `docs/<scope>-<topic>` for documentation-only changes
+- `chore/<scope>-<topic>` for maintenance and tooling updates
+- `release/<version>` only when stabilizing a public package release candidate
+
+Rules:
+
+- Branch from the latest default integration branch, normally `main`.
+- Keep topic branches focused on one slice of work.
+- Rebase or merge from the default integration branch regularly if the branch stays open.
+- Merge back to the default integration branch through a pull request.
+- Do not push directly to the default integration branch; enforce this with a GitHub ruleset or branch protection rule.
+- Do not publish packages directly from topic branches.
+
+`release/<version>` branches are optional and should be used only when a version needs stabilization passes, packaging rehearsals, or manual workflow runs without publishing from the default integration branch.
+
+## Commit Message Convention
+
+Use Conventional Commits.
+
+Preferred forms:
+
+- `feat: add transport probe state summary`
+- `fix: reject malformed session migrate ack`
+- `docs: clarify wheel build prerequisites`
+- `chore: tighten CI dependency bootstrap`
+- `test: add protocol vector regression`
+- `refactor: simplify packet decode flow`
+
+Rules:
+
+- Keep the subject line imperative.
+- Keep the first line concise.
+- Use a scope only when it adds clarity.
+- You can use multiple local commits while iterating, but normal PRs from `feature/*`, `fix/*`, `docs/*`, or `chore/*` branches must be squashed to exactly one commit before review.
+- Only version-maintenance PRs that target or originate from `release/<version>` branches may keep multiple commits when that history is actually needed.
+
+## Pull Request Expectations
+
+Every PR should:
+
+- target the default integration branch, normally `main`
+- use the default GitHub PR template that auto-loads on the PR page; specialized reference variants remain in `.github/PULL_REQUEST_TEMPLATE/` when you need to adapt the structure
+- explain the user-facing or engineering motivation
+- summarize the main modules or flows changed
+- list the validation performed
+- mention release impact when distribution output changes
+- contain exactly one commit before review unless it is a necessary `release/<version>` branch PR
+- pass the `required-checks` GitHub Actions job before merge
+
+PRs that violate the normal one-commit rule are not reviewed until they are squashed.
+
+## Validation Expectations
+
+Before opening or merging a PR, prefer the narrowest validation that proves the touched slice:
+
+- `ruff check .`
+- `pytest -q`
+- `pytest --cov=src/nnrp --cov=scripts --cov-report=xml:artifacts/coverage/coverage.xml --cov-fail-under=90 -q` when validating the repository-wide coverage gate
+- `python -m build` when wheel or sdist output changed
+
+PRs that affect CI, packaging, or release assets should include the exact command or workflow path used for validation.
+
+Changed production lines under `src/nnrp/` or `scripts/` must also keep at least 90% line coverage in CI before merge.
+
+## Versioning and Release Notes
+
+Do not reuse a published package version. If package contents change after publication, create a new version.
+
+When preparing a release PR:
+
+- update the version source intentionally
+- confirm package metadata is correct
+- confirm release assets have the expected names
+- note any manual steps required on registries
+
+Public package publishing is gated through the `Release` workflow and should only happen from a short release tag or an explicit manual dispatch.
+
+- `Release` runs on pushed `v*` tags and on manual `workflow_dispatch`; normal branch pushes must not publish GitHub releases or PyPI packages.
+- Use the `release` GitHub environment for any publish-capable job.
+- Set `PYPI_PUBLISH_MODE` on the `release` environment to `disabled`, `trusted`, or `token` so tags do not publish to PyPI accidentally before registry binding is ready.
+- If you keep token-based publishing, store `PYPI_API_TOKEN` as an environment secret on `release`, not as an unrestricted repository secret.
+- If you switch to PyPI Trusted Publisher, keep `PYPI_PUBLISH_MODE=trusted`; no PyPI secret is required, but the `release` environment is still recommended for approvals, tag restrictions, and job scoping.
+
+## Review Guidelines
+
+Review for:
+
+- protocol and wire compatibility risk
+- packaging and release regressions
+- missing tests for changed behavior
+- CI workflow correctness
+- documentation drift when user-facing behavior changes
+
+Do not start normal feature, fix, docs, or maintenance review while the PR still carries multiple commits.