PyCyphal v2

.codex/skills/cyphal-parity-guard/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: cyphal-parity-guard
+description: Keep the Python Cyphal rewrite in wire-visible behavioral parity with the C reference at `reference/cy`. Use when auditing/reviewing parity drift, identifying wire/state-machine discrepancies, updating `src/pycyphal2/` to match reference behavior, replacing conflicting Python tests with C-parity expectations, and adding regression tests for every discovered divergence. API-level discrepancies are by design and are to be ignored; this skill focuses on wire-visible and state-machine behavior only.
+---
+
+# Cyphal Parity Guard
+
+## Overview
+
+Run a deterministic parity workflow for `pycyphal2` against `reference/cy` in two modes:
+- `sync` mode: identify divergences, patch Python implementation, and add/adjust regression tests.
+- `review` mode: report parity findings only, no edits.
+
+Apply the following defaults unless the user overrides them:
+- Target wire+state parity with `cy.c`.
+- Treat `cy.c` behavior as source of truth when Python tests conflict.
+- Add Python regression coverage for each confirmed divergence.
+- Ignore API-level discrepancies that do not affect wire/state behavior (e.g., differences in API design, error handling style, etc).
+
+## Mode Selection
+
+Select mode from user intent:
+- Use `review` mode when asked to "review", "audit", or "find discrepancies".
+- Use `sync` mode when asked to "fix", "update", "bring in sync", or "correct divergences".
+- If intent is ambiguous, start in `review` mode and then switch to `sync` when requested.
+
+## Source-of-Truth Order
+
+Use this precedence:
+1. `reference/cy/cy/cy.h` for constants/API semantics.
+2. `reference/cy/cy/cy.c` for wire-visible and state-machine behavior.
+3. `reference/cy/model/` when C code intent is ambiguous.
+4. `src/pycyphal2/` and existing tests as implementation artifacts, not normative authority.
+
+## Workflow
+
+1. Prepare context.
+- Confirm repository root.
+- Inspect touched files and current test baseline.
+- Load `references/parity-checklist.md` and use it as the audit checklist.
+
+2. Build a discrepancy matrix.
+- Compare `reference/cy` behavior with `src/pycyphal2/_node.py`, `_wire.py`, and related modules.
+- Ignore differences that are not visible on the wire or in state machines (e.g., differences in API design, error handling style, etc).
+- Keep in mind that error handling differs significantly between C and Python; therefore, certain error-path-related
+  discrepancies may be expected and should be noted as such in the matrix (e.g., where C would clamp invalid
+  arguments, Python should raise ValueError, etc).
+  Error handling must be Pythonic first of all.
+- For each discrepancy, record:
+  - C anchor (`file:line` + behavior statement).
+  - Python anchor (`file:line` + divergent behavior).
+  - Impact and severity.
+  - Needed test coverage.
+
+3. Execute mode-specific actions.
+- In `review` mode:
+  - Produce findings ordered by severity.
+  - Include exact file/line anchors and missing regression tests.
+  - Do not edit code.
+- In `sync` mode:
+  - Implement fixes in `src/pycyphal2/`.
+  - Update/remove conflicting test expectations when they contradict `cy.c`.
+  - Add at least one regression test per divergence under `tests/`.
+
+4. Validate.
+- Run targeted tests first for changed behavior.
+- Run full quality gates when feasible:
+  - `nox -s test-3.12`
+  - `nox -s mypy`
+  - `nox -s format`
+- If full matrix is requested or practical, also run `test-3.11` and `test-3.13`.
+
+5. Report.
+- Always return the discrepancy matrix (resolved or unresolved).
+- For `sync` mode, map every fixed divergence to specific tests.
+- Call out residual risks if any discrepancy remains untested.
+
+## Repository Constraints
+
+Enforce project constraints while implementing parity fixes:
+- Preserve behavior across GNU/Linux, Windows, and macOS.
+- Keep support for all declared Python versions in `pyproject.toml` (currently `>=3.11`).
+- Keep async I/O in `async`/`await` style and maintain strict typing.
+- Keep formatting Black-compatible with line length 120.
+- Keep logging rich and appropriately leveled for unusual/error paths.
+
+## Output Contract
+
+For parity reviews, return:
+- Findings first, ordered high to low severity.
+- File/line references for C and Python anchors.
+- Explicit statement when no discrepancies are found.
+- Testing gaps and confidence level.
+
+For parity sync work, return:
+- What changed in implementation.
+- What changed in tests and which divergences they cover.
+- Commands executed and notable pass/fail outcomes.
+
+## Reference Map
+
+- `references/parity-checklist.md`: hotspot checklist, anchor patterns, and discrepancy matrix template.

.codex/skills/cyphal-parity-guard/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Cyphal parity guard"
+  short_description: "Keep pycyphal aligned with reference behavior"
+  default_prompt: "Use $cyphal-parity-guard to review parity against the reference and either report divergences or fix them with regression tests."

.codex/skills/cyphal-parity-guard/references/parity-checklist.md

@@ -0,0 +1,29 @@
+# Parity Checklist
+
+Use this file to drive fast, repeatable parity analysis between `reference/cy` and `src/pycyphal2/`.
+
+## High-Risk Areas
+
+1. CRDT allocation and collision arbitration.
+2. Gossip propagation, validation, scope handling, and unknown-topic behavior.
+3. Implicit topic lifecycle and retirement timing.
+4. Reliable publish ACK/NACK acceptance and association slack updates.
+5. Deduplication and reordering interaction with reliability.
+6. Response ACK/NACK and future retention semantics.
+7. Header packing/unpacking and wire constants.
+8. Consult with the reference implementation and formal models to identify additional high-risk areas.
+
+## Discrepancy Matrix Template
+
+Use one row per confirmed divergence.
+
+| ID | Area | C Anchor | Python Anchor | Divergence | Severity | Fix Plan / Action | Regression Test |
+|---|---|---|---|---|---|---|---|
+| P-001 | ACK acceptance | `reference/cy/cy/cy.c:4448` | `src/pycyphal2/_node.py:...` | Describe exact behavioral mismatch | High | Adjust ACK acceptance rules and slack handling | `tests/test_pubsub.py::...` |
+
+## Review Quality Bar
+
+Before declaring parity, ensure:
+1. Every listed high-risk area was inspected or explicitly marked not applicable.
+2. Every confirmed divergence has at least one mapped regression test (existing or new).
+3. Any changed expectation that conflicts with previous Python tests is resolved in favor of `cy.c`.

.github/workflows/docs.yml

@@ -0,0 +1,35 @@
+name: Docs
+
+on:
+  push:
+    branches: [master]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - run: pip install nox
+      - run: nox -s docs
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: html_docs/
+      - uses: actions/deploy-pages@v5
+        id: deploy

.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: Release
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - "src/pycyphal2/__init__.py"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write      # for creating tags
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Extract version
+        id: version
+        run: |
+          VERSION=$(python -c "import re, pathlib; print(re.search(r'__version__\s*=\s*\"(.+?)\"', pathlib.Path('src/pycyphal2/__init__.py').read_text()).group(1))")
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Check if tag exists
+        id: tag_check
+        run: |
+          if git ls-remote --tags origin "refs/tags/${{ steps.version.outputs.version }}" | grep -q .; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create tag
+        if: steps.tag_check.outputs.exists == 'false'
+        run: |
+          git tag "${{ steps.version.outputs.version }}"
+          git push origin "${{ steps.version.outputs.version }}"
+
+      - name: Check if version is on PyPI
+        id: pypi_check
+        run: |
+          if pip index versions pycyphal2 2>/dev/null | grep -qF "${{ steps.version.outputs.version }}"; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build package
+        if: steps.pypi_check.outputs.exists == 'false'
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        if: steps.pypi_check.outputs.exists == 'false'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}