cyphal-parity-guard

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.