feat(canopen): CANopen Safety (CiA DSP 304 V1.0) — SRDO, GFC, peer configuration and boot-up step D

[dborgards]

What does this change?

Adds CANopen Safety after CiA DSP 304 V1.0 to CanKit.Pro.CANopen, opt-in: a node opened with CanOpenNodeOptions.SrdoCount > 0 (or from a DCF that declares SRDO records) gets the objects 1300h–13FFh, an SRDO engine (producer cycle with the plain/inverted frame pair, consumer with SCT/SRVT and the order and inversion checks, EMCY 8210h), the GFC, the 13FFh checksum with the §9.5 check at the transition to Operational, EDS/DCF loading, and — for the master and tool role — the §9.2 peer configuration with readback and acknowledgement, the §8.3.1 step-D verification wired into the flying master's boot-up (while a safety slave is assigned the master sends no NMT Start to node 0: the 1F80h bit 1 start moment starts every seen slave individually, safety slaves after verification), and ObserveForeignSrdoAsync. Everything is reached through node.Safety() (ICanOpenSafety); ICanOpenNode is not widened. A node without SRDOs is unchanged.

Why now and why in this package: docs/reviews/2026-10-09-canopen-safety-scope.md (the eight decisions of 9 October, the design, the item table that FR-CO-035..046 cite). Norm basis is DSP 304 V1.0, the only full text available; the reconciliation against EN 50325-5:2010 / CiA 304 V1.1 is #289 (CRC initial value and byte order, the 13FFh ro/rw conflict, defaults).

Type of change

• feat — new behaviour (minor release)
• fix / perf — bug or performance fix (patch release)
• docs / test / refactor / chore / ci — no release
• Breaking change (! in the title, plus a BREAKING CHANGE: footer explaining the migration)

Notes a reviewer should know:

• CanOpenNodeOptions.With(...) gained two parameters; the 1.3.0 thirteen-parameter overload is kept beside it (binary-compatible, [EditorBrowsable(Never)], covered by a reflection test). With(...) now validates its result (the same ArgumentOutOfRangeException OpenNode would throw, only earlier) — documented in the package README under "Changes since 1.3.0".
• The API approval CanKit.Pro.CANopen.approved.txt was regenerated from the .received.txt; the diff is additive apart from that With line pair.
• FlyingMasterSignal.SlaveSafetyConfigurationInvalid, ForeignPdoKind.Srdo, SrdoInvalidReason.ActuationRefused and SrdoInvalidReason.MappedObjectUnavailable are additive enum members.
• §8.4.2.3 does not exist in DSP 304 V1.0 (§8.4.2 ends at §8.4.2.2); the branch cited it in a loader finding, an exception message and comments until b5868dd. The "at most 16 mapping sub-indices" bound is this implementation's (byte-aligned entries in 8 bytes); the specification allows 2, 4–128, and bit-granular mapping is not built. An SRDO maps objects of fixed width only (no strings or domains); a PDO is unchanged. SRDO frames and the GFC are classic CAN frames: a CAN FD frame or a payload over 8 bytes on those ids is rejected (the consumer goes to Mismatch; an FD frame on 001h is no GFC).
• A DCF's highest SRDO number N implies records 1..N (13FFh:00, §8.4.2.2): the loader keeps an undeclared record below N deleted, with a finding and the node's default access, and the peer-SDO gate (FR-CO-029) treats those records of a bound file as declared — the one exception to the gate, scoped to SRDO records. A consequence for FR-CO-046: a live SRDO mapping is read in full, the gate can no longer refuse it mid-mapping.
• A safety transaction (ConfigurePeerSafetyAsync, VerifyPeerSafetyConfigurationAsync) holds the peer's SDO channel for its whole length; a concurrent SDO call of this node to that peer is refused with the "already in flight" exception a concurrent transfer already produced before, so callers see no new behaviour.
• The live mapping read the PDO and the SRDO observer share now accepts mapping sub-index 0 only at exactly one byte and a slot only at exactly four bytes; anything else counts as "not read" and the bound file decides. main accepted any length ≥ 1 and ≥ 4 for the PDO observer, so that observer tightens with it.
• The DCF loader's SRDO steps and the safety write validator are static over an explicit ObjectDictionary; PeerSafetyConfiguration.FromDeviceDescription builds its expectation by running them on a dictionary of its own (CanOpenNode.LoadDescribedSafetyObjects), so a DCF reads the same on both sides by construction. The node's findings and its 13FEh-last order are unchanged.

Checklist

• dotnet build CanKit.Pro.sln -c Release succeeds (with -p:CI=true, 0 warnings)
• dotnet test CanKit.Pro.sln -c Release passes (net10.0 leg locally, every test; the net48 leg runs in CI, the Safety classes were also run on net48 locally)
• Public API changes are documented with XML comments
• New behaviour is covered by a test
• The requirement or ADR this relates to is referenced: FR-CO-035..046 (SRS §4.3.2), ADR-12, scope record docs/reviews/2026-10-09-canopen-safety-scope.md, CANopen Safety: reconcile the CiA 304 implementation against EN 50325-5:2010 / CiA 304 V1.1 #289

Also run locally: dotnet format CanKit.Pro.sln --verify-no-changes (clean) and dotnet pack into a fresh directory + eng/verify-packages.py (9 packages ok).

Mutations run (CLAUDE.md § Before claiming something is true)

Each mutation was applied to the source, the named test watched red, the source restored.

• SrdoEngine.Transmit sends the plain payload twice → A_Transmission_Is_A_Plain_Frame_And_Its_Inverse_On_Following_Ids red.
• ArmSct removed from OnSecondFrame → Valid_Pair_After_Expiry_Rearms_Sct, Each_Pair_Restarts_The_Sct red; IsInversePair reduced to a length check → A_Wrong_Inverse_Is_A_Mismatch red; DisarmConsumer emptied → the Leave/Rebuild teardown tests red; SetValid/SrdoReceived swapped → the event-order test red.
• Producer: the old "report only with a reason" condition → the vanished-SRDO test red; the finally restart removed → six tests red; stale-timer protection removed → four re-arm tests red; CycleHandle?.Dispose() removed → the tracking-actor handle test red.
• Validator: four rules broken in turn → their tests red; safety indices excluded from IsRestorableObject → the store/reset, Reset Node and "load" tests red; the static managed check reinstated → the DeclareGuard tests red.
• Node: 13FEh = A5h written before the checksums → Commit_Writes_Checksums_Then_Valid red; Arm scheduling regardless of ConfigurationValid → the tampered-checksum test red; _srdo.LeaveOperational() removed from PerformNmtReset / ApplyNmtTransition → the reset / Enter-Pre-Operational tests red; the GFC routed through the send chain → The_Gfc_Does_Not_Wait_For_An_Unconfirmed_Pair red; the in-flight bound removed → four pairs handed over instead of one; the pending slot turned back into a drop → the coalesce test red; a refused write clearing 13FEh → the Operational-abort test red; the own GFC echo dropped → the echo test red in both worlds.
• Loader: the 13FEh rank dropped, 13FEh applied before the deferred creates, the failed-mapping check removed, the TryGet guard removed → the named description tests red.
• Peer: the acknowledgement before the readback → Configure_Does_Not_Acknowledge_When_The_Readback_Differs red; sub3 not written for a producer → the producer-SRVT and consumer tests red; the first delete pass dropped → the COB-ID swap test red; srvt ?? 0 kept → both default-SRVT cases red; the range check in PeerSafetyConfiguration.Add disabled → the range cases red (the Configure-side check behind it is a second line no test can reach any more and claims no kill).
• Boot-up: the verification result ignored → the optional- and mandatory-slave tests red; the hold check removed → the hold test red; the generation check removed → the stale-result test red; the CTS cancel removed → the role-loss test red; both I1 guards removed → the second-reaction test red; _slaveVerified set unconditionally in the hold → the failed-in-hold test red.
• Foreign SRDO: the continue on a read-but-different live word removed → the live-wins test red; the file fallback after a gate refusal reinstated → the gate test red; the dummy check, the high-bit check and the parameter name each → their test red.
• Whole-branch review fix wave (each on its own): the 16-slot mapping loop restored → the two narrow-DCF tests and the leftover-slot test red; the 13FFh:n filter in Verify removed → Verify_Ignores_The_Checksum_Of_A_Deleted_Srdo red; the Operational period's token not passed to SendControlFrame, not cancelled on leave, not cancelled on dispose, or its source reused across periods → the queued-pair, pending-pair, dispose and token tests red; Array.Clear on leave removed → A_Pair_Pending_Before_A_Stop_Is_Not_Sent_After_The_Next_Start red; FromDeviceDescription runs the device loader's own SRDO code on a dictionary of its own, so the loader rules were mutated instead (the pair check at create, the two-following-ids check on the sub6 write, the collision check at create, the pre-defined pair, the inverted-slot check at the count and on the slot write, the application objects, the validator, the deferred creates, 1300h) → each red in its device test and, except the two inverted-slot checks taken alone, in the agreement Theory rows at node 5, 6 and 70; the deleted-record check and the file fallback in ObserveForeignSrdoAsync removed → their tests red; the count > 16 guard disabled → both cases red; ThrowIfDisposed in GetSrdoState removed → its test red; each SrdoCrc.Compute bound, the bound on the unrounded value and AwayFromZero rounding → their cases red; PeerSafetyConfiguration.Add keeping the caller's instance → its test red.
• Bot-review round (PR feat(canopen): CANopen Safety (CiA DSP 304 V1.0) — SRDO, GFC, peer configuration and boot-up step D #291): the node-0 broadcast restored → the keep-alive and mixed-network boot-up tests red; the start moment skipped → the "started at the start moment" assertions red; the expectation cache ignoring the bound description → its test red; the SRDO removal loop restored → the gapped-file loader and peer tests red; the gap finding dropped → both loader tests red; the peer-gate exception removed, its bound by the highest declared SRDO removed, its sub-index limit removed → the gapped Configure/Verify/step-D tests, the gate Theory rows and the foreign read-in-full test red.
• Codex round two: the width check in SrdoMapping.Add(PdoMappingEntry) dropped → the bad-width and configured-SRDO-stays-intact tests red; the 13FFh:00 clamp restored → the 65/255 Configure and Verify tests red. (The PDO twin of the width gap predates this branch: PdoMapping.Add(PdoMappingEntry) accepts a default or zero-width entry #292.)
• Codex round three: the trial run of a local SRDO configuration skipped → the five destroyed-configuration tests red (records compared byte for byte before and after); each rule in PeerSafetyConfiguration.Add (direction, COB-ID pair, times, in-configuration collision) dropped → its row red.
• Codex round four: the GFC handed over without the period token → the four GFC token tests red; the cancelled GFC send left unwrapped → the quiet-end test red.
• Codex round five: the write gate around the transition into Operational removed → A_Direct_Safety_Write_Holding_The_Gate_Is_Stored_Before_The_Node_Enters_Operational red (the state flips while a writer holds the gate).
• Codex round six: each rule of the peer-mapping pre-check against the bound file (declared, sub-index declared, PDOMapping, width, access for the direction) and the call to the check itself dropped → its Theory row red.
• Codex round seven: a public SDO call not consulting the peer's channel, the transaction not holding it across transfers, the transaction not waiting for an in-flight call, the wait ignoring its token, the channel released after the call's task completes → the channel tests and the readback-gap seam test red.
• Codex round eight: the consumer's refused write ignored for validity, SrdoReceived still raised, the DeclareGuard rule for SRDO-mapped objects dropped, the producer's width check dropped (a zero-filled pair goes out), the file fallback's even-slot check dropped (also fails the validator and loader tests — one shared predicate), the GFC call not awaiting its send, the caller token not linked → each its test red.
• Codex round eight, follow-up: the fixed-width rule dropped at the validator (fails the validator, loader and local pre-check tests at once — one code point), at the peer pre-check, and the cut-or-pad copy restored in BuildPayload → red.
• Codex round nine: the live even-slot check dropped, an unreadable even slot reported as not decoded, a differing even slot falling back to the file, 13FFh:00 accepted with any length, the upload or the download Core reading the live binding instead of the transaction's captured description → each its test red.
• Codex round ten: the upload or the download Core reading the live description instead of the transaction's snapshot, the live mapping count accepted at any length, a slot accepted beyond four bytes, a size-0 segmented upload completing without a segment request → each its test red.
• Codex round ten, follow-up: the inverted-slot width check loosened → the 5-byte 1381h:02 row red; the transaction's snapshot taken before it owns the peer's channel → the edit-while-waiting test red. The peer-safety and foreign-SRDO test classes run entirely on a virtual clock (the no-answer tests move it past the SDO timeout); hang guards are the only wall-clock dependence left.
• Codex round eleven: the > 8-byte check or the CAN FD check on an SRDO id dropped, the FD check on 001h dropped, the live COB-ID 1 read at ≥ 4 bytes, the live direction read at ≥ 1 byte → each its test red.
• Codex round twelve: Configure or Verify reading the live configuration after the count await instead of its copy, a reserved direction (3..255) counted as an existing record → each its test red.
• Not killed, by design: the token given to Task.Run in SendControlFrame (the start of the send task) can be removed without a Safety test going red: it closes a thread-scheduling window no deterministic test can open, and the check before each frame covers every testable scenario. How far the token reaches is stated in the README ("Producer") and is bounded by CanBusService.SendConfirmedAsync does not check its token before the driver call #294. Likewise dropping the _srdo.IsOperational guard in OnSrdoPairCompleted survives every test. It is an equivalent mutant: the pending slot is cleared in the same actor turn that leaves Operational, and dispose is caught by the _disposed check. The guard stays as defence in depth; no test claims it.
• Maintainer review of f5b6c79 and Codex on aeb3bbc: ObserveForeignSrdoAsync searches the records the description implies (its highest declared communication or mapping record, as the loader and the gate read it) → A_Record_Implied_By_A_Mapping_Declaration_Is_Matched red without it; the observer takes the peer's SDO channel without waiting and holds it across its whole live snapshot, so a safety transaction starting in between waits and a busy channel at the start makes the whole snapshot the file's → A_Safety_Transaction_Starting_Mid_Snapshot_Waits_For_The_Observer red without the hold. The PDO observer keeps main's per-upload reads (ObserveForeignPdoAsync: a caller cutting in between its uploads mixes a live COB-ID with the file's mapping #295). An SRDO over a deactivated mapping (L = 0, §8.1.3.1) stays as designed; the thread says why. Codex on 7da0944: the boot-up's step-D expectation is taken once the verification owns the slave's SDO channel, from the description bound then — the moment of the transaction's own snapshot — instead of on the actor turn that queued it → Step_D_Takes_Its_Expectation_When_It_Owns_The_Peer_Channel red without it. Codex and Cursor on ee6686d: a safety transaction reads the bound description once (DescribedObjects) and derives the expectation, the gate and the pre-check from that reading — no deterministic test for an edit between two readings, the structure is the claim; a step D that found no safety DCF records nothing and the boot looks again → A_Verification_That_Found_No_Dcf_Does_Not_Count_As_Verified_For_A_Dcf_Bound_Later red with the latch restored. Codex on 47408bf (a concurrent structural edit during the one reading): a property of the mutable description model shared with the gate and the loader on main → CanOpenDeviceDescription: a bound description is read without synchronization against in-place structural edits #296, no change here.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 81842ffafe

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[dborgards]

Review of head f5b6c79: one confirmed finding.

[P2] Search SRDO communication records implied by mapping declarations — CanOpenNode.ForeignSrdo.cs, lines 89–91.

MatchSrdoAsync derives its search limit only from explicitly declared communication records. The loader and peer-SDO gate also imply communication records through the highest declared mapping record (FR-CO-029). Consequently, a peer can be configured successfully but its valid SRDO pair cannot be observed (FR-CO-046).

Confirmed with a focused reproduction: remove 1301h and 1302h from the fixture while retaining 1381h and 1382h; load the device from that description and configure its safety parameters. Configuration succeeds, and an explicit upload of 1301h:05 returns 109h. ObserveForeignSrdoAsync nevertheless returns a null observation with “no SRDO communication record of the peer uses this COB-ID 1” because its search count is zero.

Use the existing DescribedSrdoCount(description) for the search limit so both communication and mapping declarations contribute.

Validation: all 880 existing CANopen tests passed on .NET 10. The focused reproduction failed at the expected non-null-observation assertion. Its temporary source was removed; no production changes were made. No confirmed standards findings.

[dborgards]

Fixed in aeb3bbc.

MatchSrdoAsync now takes its search limit from DescribedSrdoCount(description), the same reading the loader (CanOpenNode.DeviceDescription.cs) and the peer SDO gate (CanOpenNode.PeerSdo.cs) use, so a communication record implied by a mapping declaration is searched too. The method's summary says so.

Regression test: CanOpenForeignSrdoTests.A_Record_Implied_By_A_Mapping_Declaration_Is_Matched — the fixture without every 1301h and 1302h section, the device loaded from it, the peer configured with SRDO 1 on 109h/10Ah (succeeds, and the device's 1301h:05 reads 109h), then ObserveForeignSrdoAsync on 109h must decode the pair from the live mapping. Watched red on f5b6c79 with exactly the reason quoted above ("no SRDO communication record of the peer uses this COB-ID 1"), green after the change.

Local gate on aeb3bbc: build with CI=true (0 warnings), 1880 tests on net10.0 passed, dotnet format --verify-no-changes clean, pack + verify-packages.py ok (9 packages), requirements traceability 0 new untraced.

Not mergeable yet: the new head re-triggers the reviewers and the checks. I will say so once they have settled.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: aeb3bbc033

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7da0944fed

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit ee6686d. Configure here.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ee6686d6fd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 47408bfa34

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".