SAPIENT conformance, layer by layer

1. 1. Syntactically valid protobuf. Do the bytes decode as a SapientMessage?
2. 2. Structurally valid messages. Are the fields the ICD makes mandatory present, and in the right form?
3. 3. Semantically valid content. Do the values make sense, individually and against what the node registered?
4. 4. Stateful, sequence-level conformance. Does the node behave correctly over the whole session?

Layers 3 and 4 are where a node can satisfy a parser and still fail an integration. They are also the hardest to see by reading one message at a time.

1. Syntactically valid protobuf

SAPIENT messages are Protocol Buffers, each sent over TCP behind a 4-byte little-endian length prefix. Problems at this layer are usually framing: a big-endian length, a missing prefix, or two messages written into one length. The result is either a decode error or, worse, a message that decodes into nonsense.

Protobuf is forgiving. In proto3 nearly any byte string decodes into something, and every field is optional on the wire. Decoding successfully proves very little.

Tools: the language bindings implement the framing; the Wireshark dissector shows you whether it's right on the wire.

2. Structurally valid messages

BSI Flex 335 marks many fields as mandatory, and constrains the form of others. A message can decode and still be missing them. For example:

• no timestamp, or a node_id that isn't a UUID v4;
• a Registration with no capabilities, no status definition or no mode definitions;
• an enumeration left at its unspecified zero value where a real value is required.

3. Semantically valid content

Every field present and well-formed, but the content wrong or inconsistent with what the node has said about itself:

• an icd_version other than the one the node claims to implement (BSI Flex 335 v2.0);
• two modes registered with the same name, so a mode-change task can't say which it means;
• a registration with no default mode, so nobody knows which mode the node starts in;
• a detection classified as something the active mode never declared it could detect, or located in a coordinate system the mode didn't declare.

A Fusion Node that relies on the registration to interpret reports, which is the point of registration, will mishandle all of these.

4. Stateful, sequence-level conformance

The protocol is a conversation, not a series of independent messages. Correct behaviour depends on what has already happened in the session:

Sequencing

Registration must come first. A status report or detection sent before the RegistrationAck, or a task sent before the Fusion Node has accepted the Edge Node's registration, is a sequencing error.

Acknowledgements that match real requests

A TaskAck must refer to a task that was actually issued and is still outstanding; an AlertAck must refer to an alert that was actually raised. An acknowledgement that matches nothing usually means IDs are being regenerated or copied incorrectly.

Valid state transitions

A task's acknowledgements must progress through a sensible lifecycle. The same status repeated, or a status that goes backwards, leaves the two sides with different ideas of where the task is.

No unsolicited mode changes

An Edge Node's mode should change when a Fusion Node tasks it to. If a status report claims a mode the node was never tasked into, the Fusion Node's picture of the sensor is now wrong.

Timing

An Edge Node registers a status interval and must report within it. Reports that arrive late, or whose timestamps go backwards, look to a Fusion Node like a degraded or failed sensor.

None of these is visible in any single message. Finding them means tracking the session: who has registered, the declared modes and the active one, which tasks and alerts are awaiting acknowledgement, and when the last report arrived.

Testing all four layers

The SAPIENT test harness runs real sessions and checks all four layers. Message-level rules apply to every message it receives; session-level rules come from state machines for both the Edge Node and Fusion Node roles. Every rule is listed in the conformance rule catalogue.

A conformance tool is only as good as its reading of the standard. Where the harness and BSI Flex 335 disagree, the standard wins. Please report the discrepancy.