Merge branch 'feature/golden-vector-matrix'

Author: glocker

.github/workflows/golden-vectors.yml

@@ -0,0 +1,50 @@
+name: Golden vectors
+
+# Rebuilds official libcsp v2.1 (commit 48f7fb0) from source, regenerates every
+# committed CAN capture under tests/golden_vectors/, and fails if the fresh
+# capture differs from what is committed. This catches an upstream libcsp
+# change (or a moved v2.1 tag) even when no local change triggers the run.
+on:
+  schedule:
+    - cron: "0 3 * * *" # nightly, 03:00 UTC
+  push:
+    branches: [main]
+    paths:
+      - "tests/golden_vectors/**"
+      - "Dockerfile"
+      - "docker-compose.yml"
+  pull_request:
+    paths:
+      - "tests/golden_vectors/**"
+      - "Dockerfile"
+      - "docker-compose.yml"
+  workflow_dispatch: {}
+
+jobs:
+  regenerate-and-diff:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build the libcsp golden-vector image
+        run: docker compose build
+
+      - name: Start the golden-vector container
+        run: docker compose up -d
+
+      - name: Regenerate every committed vector from a fresh libcsp build
+        run: docker compose exec -T libcsp-vectors /app/tests/golden_vectors/scripts/regenerate-vectors.sh
+
+      - name: Stop the golden-vector container
+        if: always()
+        run: docker compose down
+
+      - name: Fail if regenerated vectors differ from committed fixtures
+        run: |
+          if ! git diff --exit-code -- tests/golden_vectors/*.txt; then
+            echo "::error::Freshly captured CAN traffic from libcsp v2.1 (48f7fb0) no longer matches the committed golden vectors."
+            echo "::error::Either upstream libcsp changed on-wire behavior, or a committed fixture is stale. Investigate before merging."
+            exit 1
+          fi

CHANGELOG.md

@@ -16,7 +16,10 @@ still pre-release.
 - Deterministic discrete-event simulation engine with virtual time.
 - libcsp-compatible CSP v2 single-frame codec, validated against
   repository-owned golden vectors generated from official libcsp `v2.1`.
-- Dockerized golden-vector generation workflow (`vcan0` + `candump`).
+- Dockerized golden-vector generation workflow (`vcan0` + `candump`), with a
+  committed vector matrix covering priority, address truncation, payload
+  bounds, CRC32/HMAC flags, and reversed source/destination, plus a nightly
+  CI job that rebuilds libcsp and fails on drift from the committed fixtures.
 - In-memory transport adapter for CI/tests and a SocketCAN adapter for
   Linux/HIL.
 - Pydantic schemas for TOML setup config and YAML scenario scripts.

tests/golden_vectors/README.md

@@ -48,6 +48,25 @@ The container workflow uses `vcan0` consistently.
    /app/tests/golden_vectors/bin/csp_client -c vcan0 -p -d 2
    ```
 
+   The helper's full option set (`-p -h` for usage) covers the committed
+   vector matrix:
+
+   ```text
+   -a <source-address>       CSP source/interface address (default: 1)
+   -d <destination-address>  CSP destination address (default: 2)
+   -r <priority>             CSP priority 0-3: 0=critical 1=high 2=norm 3=low
+   -l <payload-length>       payload bytes, 0-4; incrementing pattern from 0x55
+   -o <flag[,flag...]>       comma-separated CSP options: crc32, rdp, hmac
+   ```
+
+   `-o rdp` cannot be captured this way: RDP is a stateful, connection-oriented
+   protocol that blocks on a SYN handshake with no peer on the bus to answer
+   it. The RDP flag bit is covered by a synthetic pack/decode round trip in
+   `tests/test_csp_v2.py` instead of a captured vector. `crc32`/`hmac` append
+   their own trailer to the payload, so use `-l 0` with them to stay within
+   the v1 single-frame payload limit (a 1-byte payload plus a 4-byte trailer
+   would push libcsp into multi-frame transmission, which is out of v1 scope).
+
 5. `candump -n 1` exits after the first received frame. Commit the resulting
    fixture files under `tests/golden_vectors/`.
 
@@ -60,6 +79,40 @@ The container workflow uses `vcan0` consistently.
 6. Commit a sibling metadata file next to each dump, for example
    `ping.meta.toml` for `ping.txt`.
 
+To regenerate every committed vector at once (for example, to check for
+upstream libcsp drift before merging a codec change), run the same script CI
+uses instead of repeating steps 3-5 by hand:
+
+```sh
+docker compose exec -T libcsp-vectors /app/tests/golden_vectors/scripts/regenerate-vectors.sh
+```
+
+Then inspect `git diff -- tests/golden_vectors/*.txt`. An empty diff means
+libcsp's on-wire behavior still matches every committed fixture.
+
+## Committed vector matrix
+
+| Vector | Covers |
+| --- | --- |
+| `ping_node_2` (`ping.txt`) | Baseline: `src=1 dst=2 prio=NORM flags=none payload=1B` |
+| `priority_critical` | `prio=0` (CRITICAL), the low end of the 2-bit priority field |
+| `priority_low` | `prio=3` (LOW), the high end of the 2-bit priority field |
+| `high_address` | `src=65 dst=66`: the CAN-ID `sender` field is only 6 bits (libcsp uses `interface_address & 0x3F`), so this is the only committed vector where `sender != source` -- every other vector uses addresses below 64, where they are trivially equal |
+| `payload_empty` | 0-byte application payload, the lower bound of the v1 single-frame payload range |
+| `payload_max` | 4-byte application payload, the upper bound of the v1 single-frame payload range |
+| `flag_crc32` | `CSP_FLAG_CRC32` set |
+| `flag_hmac` | `CSP_FLAG_HMAC` set |
+| `reverse_direction` | `src=2 dst=1`: the same node pair as the baseline, addressed the other way |
+
+`CSP_FLAG_RDP` has no committed vector (see the generation-workflow note
+above); it is covered by a synthetic pack/decode round trip instead.
+
+Regenerating every vector and diffing against what is committed is required
+before merging any change to `tests/golden_vectors/src/csp_client.c` or
+`src/cubesat_testbed/protocol/csp_v2.py`, and also runs nightly in CI (see
+`.github/workflows/golden-vectors.yml`) so an upstream libcsp change (or a
+moved `v2.1` tag) is caught even without a local change triggering it.
+
 ## Fixture contract
 
 Every traffic dump must have a sibling `*.meta.toml` file. For example:

tests/golden_vectors/flag_crc32.meta.toml

@@ -0,0 +1,15 @@
+name = "flag_crc32"
+capture = "flag_crc32.txt"
+libcsp_repo = "https://github.com/libcsp/libcsp"
+libcsp_tag = "v2.1"
+libcsp_commit = "48f7fb0"
+command = "/app/tests/golden_vectors/bin/csp_client -c vcan0 -p -d 2 -o crc32 -l 0"
+capture_command = "candump -n 1 vcan0 > /app/tests/golden_vectors/flag_crc32.txt"
+interface = "vcan0"
+meaning = "Single-frame CSP v2 ping-port request from node 1 to node 2 with the CSP_FLAG_CRC32 header bit set and a zero-byte application payload (libcsp appends its own 4-byte CRC32 trailer to the payload; using a 1-byte application payload here would push the packet over the v1 single-frame limit and into multi-frame libcsp transmission, which is out of v1 scope). Covers the CRC32 flag bit; the testbed's v1 codec treats CSP flags as an opaque bitmask and does not itself compute or verify the CRC."
+protocol = "CSP v2 over classic CAN 2.0B extended frame"
+source_address = 1
+destination_address = 2
+expected_flags = 1
+expected_extended_can_id = "0x10004083"
+expected_payload_hex = "00 04 14 81 00 00 00 00"

tests/golden_vectors/flag_crc32.txt

@@ -0,0 +1 @@
+  vcan0  10004083   [8]  00 04 14 81 00 00 00 00

tests/golden_vectors/flag_hmac.meta.toml

@@ -0,0 +1,15 @@
+name = "flag_hmac"
+capture = "flag_hmac.txt"
+libcsp_repo = "https://github.com/libcsp/libcsp"
+libcsp_tag = "v2.1"
+libcsp_commit = "48f7fb0"
+command = "/app/tests/golden_vectors/bin/csp_client -c vcan0 -p -d 2 -o hmac -l 0"
+capture_command = "candump -n 1 vcan0 > /app/tests/golden_vectors/flag_hmac.txt"
+interface = "vcan0"
+meaning = "Single-frame CSP v2 ping-port request from node 1 to node 2 with the CSP_FLAG_HMAC header bit set and a zero-byte application payload (libcsp appends its own 4-byte HMAC trailer to the payload; using a 1-byte application payload here would push the packet over the v1 single-frame limit and into multi-frame libcsp transmission, which is out of v1 scope). Covers the HMAC flag bit; the testbed's v1 codec treats CSP flags as an opaque bitmask and does not itself compute or verify the HMAC."
+protocol = "CSP v2 over classic CAN 2.0B extended frame"
+source_address = 1
+destination_address = 2
+expected_flags = 8
+expected_extended_can_id = "0x10004083"
+expected_payload_hex = "00 04 14 88 FB DB 1D 1B"

tests/golden_vectors/flag_hmac.txt

@@ -0,0 +1 @@
+  vcan0  10004083   [8]  00 04 14 88 FB DB 1D 1B

tests/golden_vectors/high_address.meta.toml

@@ -0,0 +1,15 @@
+name = "high_address"
+capture = "high_address.txt"
+libcsp_repo = "https://github.com/libcsp/libcsp"
+libcsp_tag = "v2.1"
+libcsp_commit = "48f7fb0"
+command = "/app/tests/golden_vectors/bin/csp_client -c vcan0 -p -a 65 -d 66"
+capture_command = "candump -n 1 vcan0 > /app/tests/golden_vectors/high_address.txt"
+interface = "vcan0"
+meaning = "Single-frame CSP v2 ping-port request from node 65 to node 66. The CSP v2 CAN ID's 'sender' field is only 6 bits wide (libcsp uses the low 6 bits of the outgoing interface address), so at source=65 it diverges from the full 14-bit CSP source address (sender = 65 & 0x3F = 1, not 65): the only committed vector where these two fields are not numerically identical, since every other vector uses source/destination addresses below 64."
+protocol = "CSP v2 over classic CAN 2.0B extended frame"
+source_address = 65
+destination_address = 66
+expected_sender = 1
+expected_extended_can_id = "0x10084083"
+expected_payload_hex = "01 04 14 80 55"

tests/golden_vectors/high_address.txt

@@ -0,0 +1 @@
+  vcan0  10084083   [5]  01 04 14 80 55

tests/golden_vectors/payload_empty.meta.toml

@@ -0,0 +1,14 @@
+name = "payload_empty"
+capture = "payload_empty.txt"
+libcsp_repo = "https://github.com/libcsp/libcsp"
+libcsp_tag = "v2.1"
+libcsp_commit = "48f7fb0"
+command = "/app/tests/golden_vectors/bin/csp_client -c vcan0 -p -d 2 -l 0"
+capture_command = "candump -n 1 vcan0 > /app/tests/golden_vectors/payload_empty.txt"
+interface = "vcan0"
+meaning = "Single-frame CSP v2 ping-port request from node 1 to node 2 with a zero-byte application payload: only the 4-byte CSP v2 header extension is carried, covering the lower bound of the v1 single-frame payload range."
+protocol = "CSP v2 over classic CAN 2.0B extended frame"
+source_address = 1
+destination_address = 2
+expected_extended_can_id = "0x10004083"
+expected_payload_hex = "00 04 14 80"