feat(mqtt): SparkplugCodec decode + golden payload vectors

Decodes Sparkplug-B wire bytes into a driver-side projection (SparkplugPayload /
SparkplugMetric / SparkplugValueKind) for the Task 21 ingest state machine.

- Never throws, for ANY input. It sits on MQTTnet's shared dispatcher thread, so
  an escaping exception would stall delivery for every subscription on the
  connection, not one tag. Garbage, truncation, zero-length, a valid protobuf of
  another schema and an over-nested Template all resolve to a verdict.
- Zero-length input is INVALID, not "a payload with no metrics" — protobuf would
  parse it as all-defaults, and that is how a truncated-to-nothing body gets
  mistaken for a well-formed one.
- Explicit presence throughout (Has{Seq,Name,Alias,Datatype,Timestamp}), never a
  zero-check: an NBIRTH legitimately carries seq = 0, and every DATA metric after
  a birth carries an alias with no name and no datatype.
- Values are projected RAW, boxed, with the value oneof reported as an explicit
  ValueKind — Absent / Null / Scalar / Unsupported all mean different things and
  three of them carry a null value. DataSet/Template/extension decode as
  Unsupported (v1 scope) rather than throwing or silently vanishing.
- ReinterpretSigned() undoes Sparkplug's two's-complement-in-an-unsigned-field
  encoding of Int8/16/32/64. Kept out of decode because a DATA metric carries no
  datatype — only the consumer, holding the birth's alias table, knows which
  applies. Skipping it publishes 4294967254 for a tag whose value is -42.
- Datatype is carried as the generated Org.Eclipse.Tahu.Protobuf.DataType; the
  SparkplugDataType map is Task 17's and is applied downstream (Task 21).

Golden vectors: nbirth.bin (seq=0, named/aliased catalog, a negative Int32, an
is_null metric, a DataSet metric) + ndata.bin (alias-only metrics, no name, no
datatype) are hand-built by SparkplugGoldenPayloads, committed, and pinned by a
drift guard that rebuilds and byte-compares them on every run — plus a test that
they actually reach the output directory, since a missing copy item is invisible
in source.

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Mqtt/Sparkplug/SparkplugCodec.cs

@@ -0,0 +1,311 @@
+using Google.Protobuf;
+using Org.Eclipse.Tahu.Protobuf;
+using TahuDataType = Org.Eclipse.Tahu.Protobuf.DataType;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Sparkplug;
+
+/// <summary>
+///     Decodes Sparkplug-B wire bytes into <see cref="SparkplugPayload"/> — the driver-side projection
+///     the ingest state machine consumes. Decode only; the NCMD <i>encode</i> path lives in
+///     <c>RebirthRequester</c>.
+/// </summary>
+/// <remarks>
+///     <para>
+///         <b>Nothing here throws, for any input.</b> This runs on MQTTnet's shared dispatcher thread,
+///         behind an unauthenticated firehose the plant's edge nodes publish into. An escaping
+///         exception would not degrade one tag — it would stall or kill delivery for every
+///         subscription on the connection. Garbage bytes, a truncated body, a zero-length payload, a
+///         valid protobuf of some other schema and a pathologically nested Template all resolve to a
+///         verdict: <see cref="TryDecode"/> returns <see langword="false"/> and
+///         <see cref="Decode"/> returns <see cref="SparkplugPayload.Invalid"/>.
+///     </para>
+///     <para>
+///         <b>Zero-length input is invalid, not empty.</b> Protobuf would happily parse zero bytes as
+///         "a Payload with every field defaulted", but in Sparkplug an empty MQTT body is never a
+///         legitimate message — treating it as a well-formed payload carrying no metrics is how a
+///         truncated-to-nothing body gets mistaken for a real one. It is reported as invalid.
+///     </para>
+///     <para>
+///         <b>Explicit presence is preserved, everywhere.</b> The vendored schema is proto2 precisely
+///         so absence and zero stay distinguishable, and every projection below reads
+///         <c>Has{Seq,Name,Alias,Datatype,Timestamp,IsNull}</c> rather than testing a value against its
+///         default. Two cases make this load-bearing rather than pedantic: a Sparkplug NBIRTH is
+///         REQUIRED to carry <c>seq = 0</c>, and every DATA metric after a birth carries an alias with
+///         <b>no</b> name and <b>no</b> datatype. A zero-check decoder reports "no sequence" for every
+///         birth and "" for every DATA metric name.
+///     </para>
+///     <para>
+///         <b>Values are projected raw — nothing is coerced or reinterpreted here.</b> A metric's value
+///         arrives as the CLR type of the wire field that carried it (see
+///         <see cref="SparkplugMetric.Value"/>); coercion against the authored tag's declared
+///         <c>DriverDataType</c> is the consumer's job, and follows this driver's standing rule that a
+///         value which does not fit is refused rather than silently converted. The one wire-level
+///         translation this type does offer is <see cref="ReinterpretSigned"/>, because Sparkplug's
+///         two's-complement-in-an-unsigned-field encoding of signed integers is a property of the
+///         <i>wire</i>, not of the tag.
+///     </para>
+///     <para>
+///         <b><c>DataSet</c> and <c>Template</c> metrics are out of scope for v1.</b> They decode to
+///         <see cref="SparkplugValueKind.Unsupported"/> with a null value — deliberately visible, so a
+///         consumer can warn about a metric it cannot serve instead of silently treating it as one
+///         that was never published.
+///     </para>
+/// </remarks>
+public static class SparkplugCodec
+{
+    /// <summary>Decodes Sparkplug-B wire bytes, reporting success rather than throwing.</summary>
+    /// <param name="wire">The MQTT message body.</param>
+    /// <param name="payload">
+    ///     The decoded payload on success; <see cref="SparkplugPayload.Invalid"/> otherwise. Never
+    ///     <see langword="null"/>.
+    /// </param>
+    /// <returns>
+    ///     <see langword="true"/> when the bytes parsed as a Sparkplug-B <c>Payload</c>. Protobuf is a
+    ///     permissive, self-describing-only-by-convention format, so this means "parsed" rather than
+    ///     "was genuinely produced by a Sparkplug edge node" — unknown fields are preserved by
+    ///     Google.Protobuf and simply ignored here.
+    /// </returns>
+    public static bool TryDecode(ReadOnlySpan<byte> wire, out SparkplugPayload payload)
+    {
+        payload = SparkplugPayload.Invalid;
+
+        if (wire.IsEmpty)
+        {
+            return false;
+        }
+
+        Payload proto;
+        try
+        {
+            proto = Payload.Parser.ParseFrom(wire);
+        }
+        catch (Exception)
+        {
+            // Deliberately broad. InvalidProtocolBufferException covers malformed, truncated and
+            // over-nested input, but this is the dispatcher-thread boundary: the contract is a
+            // verdict for EVERY input, and narrowing the catch would trade that guarantee for a
+            // taxonomy nobody downstream can act on.
+            return false;
+        }
+
+        var metrics = proto.Metrics.Count == 0
+            ? []
+            : new SparkplugMetric[proto.Metrics.Count];
+
+        for (var i = 0; i < proto.Metrics.Count; i++)
+        {
+            metrics[i] = ProjectMetric(proto.Metrics[i]);
+        }
+
+        payload = new SparkplugPayload(
+            IsValid: true,
+            Seq: proto.HasSeq ? proto.Seq : null,
+            TimestampMs: proto.HasTimestamp ? proto.Timestamp : null,
+            Metrics: metrics);
+
+        return true;
+    }
+
+    /// <summary>
+    ///     Decodes Sparkplug-B wire bytes, returning <see cref="SparkplugPayload.Invalid"/> when they
+    ///     cannot be decoded.
+    /// </summary>
+    /// <param name="wire">The MQTT message body.</param>
+    /// <returns>The decoded payload — never <see langword="null"/>.</returns>
+    /// <remarks>
+    ///     The convenience shape. <b>Check <see cref="SparkplugPayload.IsValid"/>:</b> an undecodable
+    ///     body and a genuinely metric-less one both present as an empty
+    ///     <see cref="SparkplugPayload.Metrics"/>, and only the flag tells them apart. Prefer
+    ///     <see cref="TryDecode"/> where the verdict drives control flow.
+    /// </remarks>
+    public static SparkplugPayload Decode(ReadOnlySpan<byte> wire) =>
+        TryDecode(wire, out var payload) ? payload : SparkplugPayload.Invalid;
+
+    /// <summary>
+    ///     Reinterprets a raw metric value as the signed integer Sparkplug encoded it as, when its
+    ///     datatype is a signed integer type; returns the value unchanged for every other datatype.
+    /// </summary>
+    /// <param name="value">
+    ///     A <see cref="SparkplugMetric.Value"/> — a <see cref="uint"/> for the 8/16/32-bit arms, a
+    ///     <see cref="ulong"/> for the 64-bit arm.
+    /// </param>
+    /// <param name="datatype">The metric's Sparkplug datatype, from its birth or its own field.</param>
+    /// <returns>
+    ///     <see cref="sbyte"/> / <see cref="short"/> / <see cref="int"/> / <see cref="long"/> for the
+    ///     signed integer datatypes; <paramref name="value"/> untouched otherwise (including when it is
+    ///     <see langword="null"/> or not the wire type the datatype implies).
+    /// </returns>
+    /// <remarks>
+    ///     Sparkplug carries <c>Int8</c>/<c>Int16</c>/<c>Int32</c> in the <b>unsigned</b>
+    ///     <c>int_value</c> field and <c>Int64</c> in the unsigned <c>long_value</c> field, as two's
+    ///     complement. Handing the raw field to a consumer publishes <c>4294967254</c> for a tag whose
+    ///     value is <c>-42</c> — a wrong value that looks entirely plausible, arrives with Good
+    ///     quality, and is invisible until someone reads a gauge. This is the single call that undoes
+    ///     it, and it is separate from the decode itself because a DATA metric carries no datatype of
+    ///     its own: only the consumer, holding the alias table built from the birth, knows which
+    ///     datatype applies.
+    /// </remarks>
+    public static object? ReinterpretSigned(object? value, TahuDataType datatype) => datatype switch
+    {
+        TahuDataType.Int8 when value is uint raw => unchecked((sbyte)raw),
+        TahuDataType.Int16 when value is uint raw => unchecked((short)raw),
+        TahuDataType.Int32 when value is uint raw => unchecked((int)raw),
+        TahuDataType.Int64 when value is ulong raw => unchecked((long)raw),
+        _ => value,
+    };
+
+    /// <summary>Projects one generated metric onto the driver-side shape, presence intact.</summary>
+    /// <param name="metric">The generated metric.</param>
+    /// <returns>The projection.</returns>
+    private static SparkplugMetric ProjectMetric(Payload.Types.Metric metric)
+    {
+        var (kind, value) = ProjectValue(metric);
+
+        return new SparkplugMetric(
+            Name: metric.HasName ? metric.Name : null,
+            Alias: metric.HasAlias ? metric.Alias : null,
+
+            // Cast, never filter: an index this build's enum does not define is a future Sparkplug
+            // revision or a misbehaving publisher, and dropping it would deny the mapping layer the
+            // only evidence it has.
+            DataType: metric.HasDatatype ? (TahuDataType)metric.Datatype : null,
+            TimestampMs: metric.HasTimestamp ? metric.Timestamp : null,
+            ValueKind: kind,
+            Value: value);
+    }
+
+    /// <summary>Resolves a metric's value <c>oneof</c> to a kind plus a raw CLR value.</summary>
+    /// <param name="metric">The generated metric.</param>
+    /// <returns>The value kind and the projected value.</returns>
+    /// <remarks>
+    ///     <c>is_null</c> wins over the <c>oneof</c>: the Sparkplug spec's whole reason for the field is
+    ///     that some datatypes have no spare sentinel, so a publisher that sets it means "null" even if
+    ///     a value field is also populated.
+    /// </remarks>
+    private static (SparkplugValueKind Kind, object? Value) ProjectValue(Payload.Types.Metric metric)
+    {
+        if (metric.HasIsNull && metric.IsNull)
+        {
+            return (SparkplugValueKind.Null, null);
+        }
+
+        return metric.ValueCase switch
+        {
+            Payload.Types.Metric.ValueOneofCase.IntValue => (SparkplugValueKind.Scalar, metric.IntValue),
+            Payload.Types.Metric.ValueOneofCase.LongValue => (SparkplugValueKind.Scalar, metric.LongValue),
+            Payload.Types.Metric.ValueOneofCase.FloatValue => (SparkplugValueKind.Scalar, metric.FloatValue),
+            Payload.Types.Metric.ValueOneofCase.DoubleValue => (SparkplugValueKind.Scalar, metric.DoubleValue),
+            Payload.Types.Metric.ValueOneofCase.BooleanValue => (SparkplugValueKind.Scalar, metric.BooleanValue),
+            Payload.Types.Metric.ValueOneofCase.StringValue => (SparkplugValueKind.Scalar, metric.StringValue),
+
+            // Copied out of the ByteString: the projection must outlive the parsed message.
+            Payload.Types.Metric.ValueOneofCase.BytesValue =>
+                (SparkplugValueKind.Scalar, metric.BytesValue.ToByteArray()),
+
+            // v1 scope boundary — decoded as a visible refusal, not as an exception or a silent drop.
+            Payload.Types.Metric.ValueOneofCase.DatasetValue => (SparkplugValueKind.Unsupported, null),
+            Payload.Types.Metric.ValueOneofCase.TemplateValue => (SparkplugValueKind.Unsupported, null),
+            Payload.Types.Metric.ValueOneofCase.ExtensionValue => (SparkplugValueKind.Unsupported, null),
+
+            _ => (SparkplugValueKind.Absent, null),
+        };
+    }
+}
+
+/// <summary>
+///     A decoded Sparkplug-B payload: the driver-side projection of the generated <c>Payload</c>,
+///     carrying only what the ingest state machine consumes.
+/// </summary>
+/// <param name="IsValid">
+///     <see langword="false"/> for a payload that could not be decoded. An invalid payload also has an
+///     empty <paramref name="Metrics"/> list, so <b>this flag is the only thing distinguishing an
+///     undecodable body from a legitimately metric-less one</b>.
+/// </param>
+/// <param name="Seq">
+///     The payload sequence number, or <see langword="null"/> when the message carried none. Kept as
+///     the wire's <see cref="ulong"/> rather than narrowed to a byte: the Sparkplug range is 0–255, but
+///     a publisher that violates it is reporting a fact the consumer should be able to see and reject,
+///     not one this layer should silently truncate into a plausible-looking sequence number.
+/// </param>
+/// <param name="TimestampMs">The payload timestamp in Sparkplug epoch milliseconds, or null when absent.</param>
+/// <param name="Metrics">The payload's metrics, in wire order. Never <see langword="null"/>.</param>
+public sealed record SparkplugPayload(
+    bool IsValid,
+    ulong? Seq,
+    ulong? TimestampMs,
+    IReadOnlyList<SparkplugMetric> Metrics)
+{
+    /// <summary>The shared "could not decode this" result.</summary>
+    public static readonly SparkplugPayload Invalid = new(false, null, null, []);
+}
+
+/// <summary>One decoded Sparkplug metric.</summary>
+/// <param name="Name">
+///     The metric's stable name, or <see langword="null"/> when the message omitted it — which every
+///     real DATA metric after a birth does, carrying only <paramref name="Alias"/>. Distinguishing
+///     this from an empty string is the reason the vendored schema is proto2.
+/// </param>
+/// <param name="Alias">The per-birth alias, or <see langword="null"/> when the metric carried none.</param>
+/// <param name="DataType">
+///     The metric's declared datatype, or <see langword="null"/> when absent (again, the normal case
+///     for a DATA metric — its datatype comes from the birth). An index this build's enum does not
+///     define is preserved as an undefined enum value rather than dropped.
+/// </param>
+/// <param name="TimestampMs">
+///     The metric's own acquisition timestamp in Sparkplug epoch milliseconds, or
+///     <see langword="null"/> when it carried none — in which case the payload's timestamp applies.
+/// </param>
+/// <param name="ValueKind">
+///     What <paramref name="Value"/> means. Check this before reading the value: a null value is
+///     ambiguous between "explicitly null", "absent" and "a kind v1 does not support".
+/// </param>
+/// <param name="Value">
+///     The <b>raw</b> wire value, boxed: <see cref="uint"/> (<c>int_value</c>), <see cref="ulong"/>
+///     (<c>long_value</c>), <see cref="float"/>, <see cref="double"/>, <see cref="bool"/>,
+///     <see cref="string"/> or <see cref="byte"/><c>[]</c> — and <see langword="null"/> for every
+///     <paramref name="ValueKind"/> other than <see cref="SparkplugValueKind.Scalar"/>.
+///     <para>
+///         <b>Signed integers arrive as their unsigned two's-complement wire value</b> — a
+///         <c>DataType.Int32</c> metric holding -42 is a <see cref="uint"/> of 4294967254 here. Run it
+///         through <see cref="SparkplugCodec.ReinterpretSigned"/> with the metric's datatype (from the
+///         birth, for a DATA metric) before publishing it.
+///     </para>
+///     <para>
+///         Boxing is deliberate: the consumer coerces against the authored tag's declared
+///         <c>DriverDataType</c> and hands the result to a <c>DataValueSnapshot</c>, which boxes
+///         anyway, so a discriminated-union shape would buy an unboxing hop and cost every consumer a
+///         switch over a dozen arms.
+///     </para>
+/// </param>
+public readonly record struct SparkplugMetric(
+    string? Name,
+    ulong? Alias,
+    TahuDataType? DataType,
+    ulong? TimestampMs,
+    SparkplugValueKind ValueKind,
+    object? Value);
+
+/// <summary>What a decoded metric's <see cref="SparkplugMetric.Value"/> represents.</summary>
+/// <remarks>
+///     Three of the four members have a null <see cref="SparkplugMetric.Value"/> and mean entirely
+///     different things, which is exactly why the distinction is carried explicitly rather than left
+///     for a consumer to infer from a null.
+/// </remarks>
+public enum SparkplugValueKind
+{
+    /// <summary>The metric's value <c>oneof</c> carried nothing at all.</summary>
+    Absent = 0,
+
+    /// <summary>The metric set <c>is_null</c>: it exists, and its value is explicitly null.</summary>
+    Null,
+
+    /// <summary><see cref="SparkplugMetric.Value"/> holds the raw wire value.</summary>
+    Scalar,
+
+    /// <summary>
+    ///     A <c>DataSet</c>, <c>Template</c> or extension value — decoded and reported, but not
+    ///     supported in v1. The consumer should warn and skip the metric rather than treat it as
+    ///     missing.
+    /// </summary>
+    Unsupported,
+}

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Tests/SparkplugCodecTests.cs

@@ -0,0 +1,392 @@
+using Google.Protobuf;
+using Org.Eclipse.Tahu.Protobuf;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Sparkplug;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Tests;
+
+/// <summary>
+///     Covers <see cref="SparkplugCodec"/>: the golden NBIRTH/NDATA vectors decode into the driver-side
+///     projection with explicit presence preserved, and no input — malformed, truncated, empty, or
+///     simply not Sparkplug — makes the decoder throw.
+/// </summary>
+public sealed class SparkplugCodecTests
+{
+    /// <summary>
+    ///     The headline case from the plan: a golden NBIRTH yields its sequence number and its metric
+    ///     catalog, with name, alias, datatype and value all surviving.
+    /// </summary>
+    [Fact]
+    public void Decode_GoldenNbirth_ExtractsMetrics()
+    {
+        var payload = SparkplugCodec.Decode(SparkplugGoldenPayloads.Read(SparkplugGoldenPayloads.NbirthFile));
+
+        payload.IsValid.ShouldBeTrue();
+        payload.Seq.ShouldBe(0UL);
+        payload.Metrics.ShouldContain(m =>
+            m.Name == "Temperature"
+            && m.Alias == 5UL
+            && m.DataType == DataType.Float
+            && Equals(m.Value, 21.5f));
+    }
+
+    /// <summary>
+    ///     <b>Explicit presence, case 1.</b> A Sparkplug NBIRTH is REQUIRED to carry <c>seq = 0</c>, so a
+    ///     decoder that reads absence off a zero value reports "no sequence" for every birth ever
+    ///     published — and the sequence tracker then has no birth to anchor on.
+    /// </summary>
+    [Fact]
+    public void Decode_GoldenNbirth_SeqZero_IsPresentNotAbsent()
+    {
+        var payload = SparkplugCodec.Decode(SparkplugGoldenPayloads.Read(SparkplugGoldenPayloads.NbirthFile));
+
+        payload.Seq.HasValue.ShouldBeTrue();
+        payload.Seq!.Value.ShouldBe(0UL);
+    }
+
+    /// <summary>
+    ///     <b>Explicit presence, case 2.</b> A payload that genuinely omits <c>seq</c> must report
+    ///     absence, not zero — the mirror image of the test above, and the pair is what makes the
+    ///     distinction falsifiable rather than incidental.
+    /// </summary>
+    [Fact]
+    public void Decode_PayloadWithoutSeq_ReportsAbsentSeq()
+    {
+        var wire = new Payload { Timestamp = 1UL }.ToByteArray();
+
+        SparkplugCodec.Decode(wire).Seq.ShouldBeNull();
+    }
+
+    /// <summary>
+    ///     <b>Explicit presence, case 3.</b> Every real Sparkplug DATA metric omits <c>name</c> and
+    ///     <c>datatype</c> and carries only its alias. Reporting an absent name as the empty string
+    ///     would make it indistinguishable from a (malformed) metric genuinely named "".
+    /// </summary>
+    [Fact]
+    public void Decode_GoldenNdata_MetricsCarryAliasOnly_NameAndDataTypeAbsent()
+    {
+        var payload = SparkplugCodec.Decode(SparkplugGoldenPayloads.Read(SparkplugGoldenPayloads.NdataFile));
+
+        payload.IsValid.ShouldBeTrue();
+        payload.Seq.ShouldBe(1UL);
+        payload.Metrics.Count.ShouldBe(3);
+
+        foreach (var metric in payload.Metrics)
+        {
+            metric.Name.ShouldBeNull();
+            metric.DataType.ShouldBeNull();
+            metric.Alias.HasValue.ShouldBeTrue();
+        }
+
+        payload.Metrics.ShouldContain(m => m.Alias == SparkplugGoldenPayloads.TemperatureAlias
+                                           && Equals(m.Value, 22.25f));
+    }
+
+    /// <summary>
+    ///     <b>Explicit presence, case 4.</b> "The metric's value is null" (<c>is_null</c>) is a different
+    ///     fact from "the metric carried no value field", and both differ from "the value is zero".
+    /// </summary>
+    [Fact]
+    public void Decode_GoldenNbirth_ExplicitNullMetric_IsNullKind()
+    {
+        var payload = SparkplugCodec.Decode(SparkplugGoldenPayloads.Read(SparkplugGoldenPayloads.NbirthFile));
+
+        var missing = payload.Metrics.Single(m => m.Name == "Missing");
+        missing.ValueKind.ShouldBe(SparkplugValueKind.Null);
+        missing.Value.ShouldBeNull();
+        missing.DataType.ShouldBe(DataType.Float);
+    }
+
+    /// <summary>
+    ///     <b>Explicit presence, case 5 — the one that makes the other four falsifiable.</b> A publisher
+    ///     may legitimately set a metric's name to the empty string, its datatype to <c>Unknown</c> (0)
+    ///     and its timestamp to 0 (the Unix epoch). Those are present-and-default, and the golden
+    ///     vectors alone cannot tell a presence check from a default check because nothing in them sets
+    ///     a field to its own default. This pins the distinction directly: set-to-default must decode as
+    ///     PRESENT, unset must decode as ABSENT, on every field that carries presence.
+    /// </summary>
+    [Fact]
+    public void Decode_FieldsSetToTheirOwnDefault_ArePresent_WhileUnsetFieldsAreAbsent()
+    {
+        var payload = new Payload();
+        payload.Metrics.Add(new Payload.Types.Metric
+        {
+            Name = string.Empty,
+            Alias = 0UL,
+            Datatype = (uint)DataType.Unknown,
+            Timestamp = 0UL,
+            IntValue = 0U,
+        });
+        payload.Metrics.Add(new Payload.Types.Metric { StringValue = "unset-everything-else" });
+
+        var decoded = SparkplugCodec.Decode(payload.ToByteArray());
+
+        var present = decoded.Metrics[0];
+        present.Name.ShouldBe(string.Empty);
+        present.Alias.ShouldBe(0UL);
+        present.DataType.ShouldBe(DataType.Unknown);
+        present.TimestampMs.ShouldBe(0UL);
+
+        var absent = decoded.Metrics[1];
+        absent.Name.ShouldBeNull();
+        absent.Alias.ShouldBeNull();
+        absent.DataType.ShouldBeNull();
+        absent.TimestampMs.ShouldBeNull();
+    }
+
+    /// <summary>A metric carrying neither a value nor <c>is_null</c> decodes as absent, not null.</summary>
+    [Fact]
+    public void Decode_MetricWithNoValueAndNoIsNull_IsAbsentKind()
+    {
+        var payload = new Payload { Seq = 4UL };
+        payload.Metrics.Add(new Payload.Types.Metric { Name = "Bare" });
+
+        var decoded = SparkplugCodec.Decode(payload.ToByteArray());
+
+        decoded.Metrics.Single().ValueKind.ShouldBe(SparkplugValueKind.Absent);
+        decoded.Metrics.Single().Value.ShouldBeNull();
+    }
+
+    /// <summary>
+    ///     Every scalar arm of the metric value <c>oneof</c> projects to a CLR value of the wire's own
+    ///     type — nothing is coerced here; coercion against the authored tag type happens downstream.
+    /// </summary>
+    [Fact]
+    public void Decode_GoldenNbirth_ProjectsEveryScalarValueArm()
+    {
+        var payload = SparkplugCodec.Decode(SparkplugGoldenPayloads.Read(SparkplugGoldenPayloads.NbirthFile));
+
+        var byName = payload.Metrics.Where(m => m.Name is not null).ToDictionary(m => m.Name!, m => m);
+
+        byName["bdSeq"].Value.ShouldBe(7UL);                     // long_value  → ulong
+        byName["Node Control/Rebirth"].Value.ShouldBe(false);    // boolean_value → bool
+        byName["Temperature"].Value.ShouldBe(21.5f);             // float_value  → float
+        byName["Pressure"].Value.ShouldBe(101.325d);             // double_value → double
+        byName["Running"].Value.ShouldBe(true);
+        byName["Serial"].Value.ShouldBe("EDGE-A-001");           // string_value → string
+        byName["Count"].Value.ShouldBe(unchecked((uint)-42));    // int_value    → uint, RAW
+    }
+
+    /// <summary>A <c>bytes</c> metric projects to a byte array rather than a protobuf <c>ByteString</c>.</summary>
+    [Fact]
+    public void Decode_BytesMetric_ProjectsToByteArray()
+    {
+        var payload = new Payload();
+        payload.Metrics.Add(new Payload.Types.Metric
+        {
+            Name = "Blob",
+            Datatype = (uint)DataType.Bytes,
+            BytesValue = ByteString.CopyFrom(1, 2, 3),
+        });
+
+        var decoded = SparkplugCodec.Decode(payload.ToByteArray());
+
+        decoded.Metrics.Single().Value.ShouldBeOfType<byte[]>().ShouldBe(new byte[] { 1, 2, 3 });
+    }
+
+    /// <summary>
+    ///     <c>DataSet</c> and <c>Template</c> metrics are out of scope for v1. They must decode to an
+    ///     explicit "unsupported" kind — never an exception on the MQTT dispatcher thread, and never a
+    ///     silently-dropped metric that looks identical to a metric that was never published.
+    /// </summary>
+    [Fact]
+    public void Decode_GoldenNbirth_DataSetMetric_IsUnsupported_NotAThrow()
+    {
+        var payload = SparkplugCodec.Decode(SparkplugGoldenPayloads.Read(SparkplugGoldenPayloads.NbirthFile));
+
+        var config = payload.Metrics.Single(m => m.Name == "Config");
+        config.ValueKind.ShouldBe(SparkplugValueKind.Unsupported);
+        config.Value.ShouldBeNull();
+        config.DataType.ShouldBe(DataType.DataSet);
+    }
+
+    /// <summary>A <c>Template</c> metric takes the same unsupported path as <c>DataSet</c>.</summary>
+    [Fact]
+    public void Decode_TemplateMetric_IsUnsupported()
+    {
+        var payload = new Payload();
+        payload.Metrics.Add(new Payload.Types.Metric
+        {
+            Name = "Motor",
+            Datatype = (uint)DataType.Template,
+            TemplateValue = new Payload.Types.Template { Version = "1", IsDefinition = false },
+        });
+
+        SparkplugCodec.Decode(payload.ToByteArray()).Metrics.Single().ValueKind
+            .ShouldBe(SparkplugValueKind.Unsupported);
+    }
+
+    /// <summary>Payload and per-metric timestamps survive as raw Sparkplug epoch milliseconds.</summary>
+    [Fact]
+    public void Decode_GoldenVectors_PreserveTimestamps()
+    {
+        var nbirth = SparkplugCodec.Decode(SparkplugGoldenPayloads.Read(SparkplugGoldenPayloads.NbirthFile));
+
+        nbirth.TimestampMs.ShouldBe(SparkplugGoldenPayloads.NbirthTimestampMs);
+        nbirth.Metrics.Single(m => m.Name == "Temperature").TimestampMs
+            .ShouldBe(SparkplugGoldenPayloads.NbirthTimestampMs);
+
+        // A metric that carried no timestamp of its own reports absence, not the payload's.
+        nbirth.Metrics.Single(m => m.Name == "Pressure").TimestampMs.ShouldBeNull();
+    }
+
+    /// <summary>
+    ///     Sparkplug carries signed integers up to 32 bits as two's complement in the UNSIGNED
+    ///     <c>int_value</c> field. The codec hands over the raw wire value; this is the helper that
+    ///     turns it back into the number the edge node meant.
+    /// </summary>
+    [Theory]
+    [InlineData(DataType.Int8, -5)]
+    [InlineData(DataType.Int16, -1234)]
+    [InlineData(DataType.Int32, -42)]
+    public void ReinterpretSigned_RecoversNegativeIntegersFromTheUnsignedWireField(DataType datatype, int expected)
+    {
+        var raw = unchecked((uint)expected);
+
+        var result = SparkplugCodec.ReinterpretSigned(raw, datatype);
+
+        Convert.ToInt64(result).ShouldBe(expected);
+    }
+
+    /// <summary>The 64-bit arm reinterprets <c>long_value</c>; the golden NBIRTH's Count is the 32-bit arm.</summary>
+    [Fact]
+    public void ReinterpretSigned_HandlesInt64_AndTheGoldenCountMetric()
+    {
+        SparkplugCodec.ReinterpretSigned(unchecked((ulong)-9_000_000_000L), DataType.Int64).ShouldBe(-9_000_000_000L);
+
+        var payload = SparkplugCodec.Decode(SparkplugGoldenPayloads.Read(SparkplugGoldenPayloads.NbirthFile));
+        var count = payload.Metrics.Single(m => m.Name == "Count");
+        SparkplugCodec.ReinterpretSigned(count.Value, count.DataType!.Value)
+            .ShouldBe(SparkplugGoldenPayloads.CountBirthValue);
+    }
+
+    /// <summary>Unsigned and non-integer datatypes pass through untouched.</summary>
+    [Fact]
+    public void ReinterpretSigned_LeavesUnsignedAndNonIntegerValuesAlone()
+    {
+        SparkplugCodec.ReinterpretSigned(7U, DataType.Uint32).ShouldBe(7U);
+        SparkplugCodec.ReinterpretSigned(21.5f, DataType.Float).ShouldBe(21.5f);
+        SparkplugCodec.ReinterpretSigned("text", DataType.String).ShouldBe("text");
+        SparkplugCodec.ReinterpretSigned(null, DataType.Int32).ShouldBeNull();
+    }
+
+    /// <summary>
+    ///     A datatype index this build's enum does not define (a future Sparkplug revision, or a
+    ///     misbehaving publisher) is preserved verbatim rather than dropped or coerced to Unknown —
+    ///     the mapping layer decides what to do with it, and it cannot decide about data it never saw.
+    /// </summary>
+    [Fact]
+    public void Decode_UnrecognisedDataTypeIndex_IsPreservedVerbatim()
+    {
+        var payload = new Payload();
+        payload.Metrics.Add(new Payload.Types.Metric { Name = "Future", Datatype = 250U, IntValue = 1U });
+
+        var decoded = SparkplugCodec.Decode(payload.ToByteArray());
+
+        ((int)decoded.Metrics.Single().DataType!.Value).ShouldBe(250);
+    }
+
+    /// <summary>
+    ///     <b>Never throws, case 1.</b> Zero-length input is not "a payload with no metrics" — it is no
+    ///     answer at all, and is reported as invalid so a truncated-to-nothing body cannot pass as a
+    ///     well-formed message with an empty metric list.
+    /// </summary>
+    [Fact]
+    public void TryDecode_EmptyInput_IsInvalid_AndDoesNotThrow()
+    {
+        SparkplugCodec.TryDecode([], out var payload).ShouldBeFalse();
+        payload.IsValid.ShouldBeFalse();
+        payload.Metrics.ShouldBeEmpty();
+        payload.Seq.ShouldBeNull();
+    }
+
+    /// <summary>
+    ///     <b>Never throws, case 2.</b> Garbage bytes: a decoder that let an exception escape here would
+    ///     take down the MQTT dispatcher thread — every subscription on the connection, not one tag.
+    /// </summary>
+    [Fact]
+    public void TryDecode_GarbageBytes_NeverThrows()
+    {
+        var random = new Random(20260724);
+
+        for (var i = 0; i < 2000; i++)
+        {
+            var bytes = new byte[random.Next(1, 64)];
+            random.NextBytes(bytes);
+
+            // The verdict is irrelevant — some random byte strings ARE valid protobuf. Not throwing is
+            // the whole assertion.
+            Should.NotThrow(() => SparkplugCodec.TryDecode(bytes, out _));
+        }
+    }
+
+    /// <summary>
+    ///     <b>Never throws, case 3.</b> Every truncation of a real payload — the shape a dropped
+    ///     connection or a size-capped broker actually produces.
+    /// </summary>
+    [Fact]
+    public void TryDecode_EveryTruncationOfAGoldenVector_NeverThrows()
+    {
+        foreach (var file in new[] { SparkplugGoldenPayloads.NbirthFile, SparkplugGoldenPayloads.NdataFile })
+        {
+            var full = SparkplugGoldenPayloads.Read(file);
+            for (var length = 0; length <= full.Length; length++)
+            {
+                var prefix = full.AsSpan(0, length).ToArray();
+                Should.NotThrow(() => SparkplugCodec.TryDecode(prefix, out _));
+            }
+        }
+    }
+
+    /// <summary>
+    ///     <b>Never throws, case 4.</b> A valid protobuf message that is not a Sparkplug payload. Protobuf
+    ///     is permissive, so this may well parse (as unknown fields) — what matters is that it neither
+    ///     throws nor invents metrics.
+    /// </summary>
+    [Fact]
+    public void TryDecode_ValidProtobufThatIsNotASparkplugPayload_NeverThrows()
+    {
+        // A DataSet message, serialized standalone — legal protobuf, wrong schema.
+        var alien = new Payload.Types.DataSet { NumOfColumns = 3UL };
+        alien.Columns.Add("a");
+
+        Should.NotThrow(() => SparkplugCodec.TryDecode(alien.ToByteArray(), out _));
+    }
+
+    /// <summary>
+    ///     <b>Never throws, case 5.</b> A deeply nested Template — protobuf's recursion limit rejects it,
+    ///     and the rejection must arrive as a verdict rather than as an exception.
+    /// </summary>
+    [Fact]
+    public void TryDecode_PathologicallyNestedTemplate_NeverThrows()
+    {
+        var template = new Payload.Types.Template { Version = "1" };
+        for (var depth = 0; depth < 200; depth++)
+        {
+            var outer = new Payload.Types.Template { Version = "1" };
+            outer.Metrics.Add(new Payload.Types.Metric { Name = "n", TemplateValue = template });
+            template = outer;
+        }
+
+        var payload = new Payload();
+        payload.Metrics.Add(new Payload.Types.Metric { Name = "Deep", TemplateValue = template });
+
+        Should.NotThrow(() => SparkplugCodec.TryDecode(payload.ToByteArray(), out _));
+    }
+
+    /// <summary>
+    ///     <see cref="SparkplugCodec.Decode"/> is the convenience shape the plan's call sites use: it
+    ///     never returns <see langword="null"/> and never throws, reporting failure through
+    ///     <see cref="SparkplugPayload.IsValid"/>.
+    /// </summary>
+    [Fact]
+    public void Decode_OnUndecodableInput_ReturnsTheInvalidPayload_RatherThanThrowing()
+    {
+        var payload = SparkplugCodec.Decode([]);
+
+        payload.ShouldNotBeNull();
+        payload.IsValid.ShouldBeFalse();
+        payload.Metrics.ShouldBeEmpty();
+    }
+}

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Tests/SparkplugGoldenPayloads.cs

@@ -0,0 +1,216 @@
+using Google.Protobuf;
+using Org.Eclipse.Tahu.Protobuf;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Tests;
+
+/// <summary>
+///     Builds the two Sparkplug-B wire vectors committed under <c>Golden/</c> — an NBIRTH and the
+///     NDATA that follows it — and names the files they live in.
+/// </summary>
+/// <remarks>
+///     <para>
+///         <b>Why a generator instead of bytes captured off a real edge node.</b> A capture would pin
+///         one vendor's encoder rather than the schema, could not be regenerated when the vendored
+///         proto is re-vendored, and would drag an unaudited third-party payload into the repo. These
+///         payloads are hand-built from the generated types, serialized once, and committed; the
+///         <c>SparkplugGoldenVectorTests</c> drift guard re-runs this builder on every test run and
+///         fails if the committed bytes no longer match, which is what makes the files an actual
+///         regression pin rather than decoration.
+///     </para>
+///     <para>
+///         <b>Every field in here is load-bearing.</b> The NBIRTH carries <c>seq = 0</c> (present and
+///         zero — the case a <c>Seq != 0</c> presence check gets wrong), a negative Int32 encoded the
+///         Sparkplug way (two's complement in an unsigned <c>int_value</c>), an explicit
+///         <c>is_null</c> metric, and a <c>DataSet</c> metric that v1 does not support. The NDATA
+///         carries metrics with <b>no name and no datatype</b> — alias only — which is how every real
+///         Sparkplug DATA message after a birth looks, and the case an "absent means empty string"
+///         decoder gets wrong. Do not "tidy" these payloads.
+///     </para>
+/// </remarks>
+internal static class SparkplugGoldenPayloads
+{
+    /// <summary>Repo-relative directory the committed vectors live in, inside the test project.</summary>
+    public const string Directory = "Golden";
+
+    /// <summary>File name of the NBIRTH vector.</summary>
+    public const string NbirthFile = "nbirth.bin";
+
+    /// <summary>File name of the NDATA vector.</summary>
+    public const string NdataFile = "ndata.bin";
+
+    /// <summary>NBIRTH payload timestamp — 2024-07-24T12:00:00Z, in Sparkplug's epoch milliseconds.</summary>
+    public const ulong NbirthTimestampMs = 1721822400000UL;
+
+    /// <summary>NDATA payload timestamp — five seconds after the birth.</summary>
+    public const ulong NdataTimestampMs = 1721822405000UL;
+
+    /// <summary>The alias the NBIRTH binds to <c>Temperature</c>, reused by the NDATA.</summary>
+    public const ulong TemperatureAlias = 5UL;
+
+    /// <summary>The alias the NBIRTH binds to <c>Count</c> — the negative-Int32 case.</summary>
+    public const ulong CountAlias = 9UL;
+
+    /// <summary>The alias the NBIRTH binds to <c>Missing</c> — the explicit-null case.</summary>
+    public const ulong MissingAlias = 11UL;
+
+    /// <summary>The <c>Count</c> metric's value in the NBIRTH — negative, to pin the wire encoding.</summary>
+    public const int CountBirthValue = -42;
+
+    /// <summary>The <c>Count</c> metric's value in the NDATA.</summary>
+    public const int CountDataValue = -43;
+
+    /// <summary>
+    ///     Builds the NBIRTH: <c>seq = 0</c>, a full metric catalog with names, aliases and datatypes.
+    /// </summary>
+    /// <returns>The payload; serialize with <see cref="MessageExtensions.ToByteArray"/>.</returns>
+    public static Payload BuildNbirth()
+    {
+        var payload = new Payload
+        {
+            Timestamp = NbirthTimestampMs,
+
+            // Present AND zero. Sparkplug REQUIRES an NBIRTH to carry seq = 0, so any decoder that
+            // infers absence from a zero value reports "no sequence" for every birth it ever sees.
+            Seq = 0UL,
+        };
+
+        payload.Metrics.Add(new Payload.Types.Metric
+        {
+            Name = "bdSeq",
+            Datatype = (uint)DataType.Uint64,
+            LongValue = 7UL,
+        });
+
+        payload.Metrics.Add(new Payload.Types.Metric
+        {
+            Name = "Node Control/Rebirth",
+            Datatype = (uint)DataType.Boolean,
+            BooleanValue = false,
+        });
+
+        payload.Metrics.Add(new Payload.Types.Metric
+        {
+            Name = "Temperature",
+            Alias = TemperatureAlias,
+            Timestamp = NbirthTimestampMs,
+            Datatype = (uint)DataType.Float,
+            FloatValue = 21.5f,
+        });
+
+        payload.Metrics.Add(new Payload.Types.Metric
+        {
+            Name = "Pressure",
+            Alias = 6UL,
+            Datatype = (uint)DataType.Double,
+            DoubleValue = 101.325d,
+        });
+
+        payload.Metrics.Add(new Payload.Types.Metric
+        {
+            Name = "Running",
+            Alias = 7UL,
+            Datatype = (uint)DataType.Boolean,
+            BooleanValue = true,
+        });
+
+        payload.Metrics.Add(new Payload.Types.Metric
+        {
+            Name = "Serial",
+            Alias = 8UL,
+            Datatype = (uint)DataType.String,
+            StringValue = "EDGE-A-001",
+        });
+
+        // Sparkplug carries every signed integer up to 32 bits in the UNSIGNED int_value field as
+        // two's complement, so -42 goes on the wire as 4294967254. A decoder that hands the raw
+        // uint32 straight to a consumer publishes 4294967254 for a tag whose value is -42.
+        payload.Metrics.Add(new Payload.Types.Metric
+        {
+            Name = "Count",
+            Alias = CountAlias,
+            Datatype = (uint)DataType.Int32,
+            IntValue = unchecked((uint)CountBirthValue),
+        });
+
+        // DataSet is explicitly out of scope for v1 — present here so "unsupported" is a decoded,
+        // testable outcome rather than an exception on the MQTT dispatcher thread.
+        var dataSet = new Payload.Types.DataSet { NumOfColumns = 1UL };
+        dataSet.Columns.Add("col0");
+        dataSet.Types_.Add((uint)DataType.Int32);
+        var row = new Payload.Types.DataSet.Types.Row();
+        row.Elements.Add(new Payload.Types.DataSet.Types.DataSetValue { IntValue = 1U });
+        dataSet.Rows.Add(row);
+
+        payload.Metrics.Add(new Payload.Types.Metric
+        {
+            Name = "Config",
+            Alias = 10UL,
+            Datatype = (uint)DataType.DataSet,
+            DatasetValue = dataSet,
+        });
+
+        // is_null = true with NO value in the oneof: "this metric exists and its value is null",
+        // which is a different fact from "this metric carried no value field".
+        payload.Metrics.Add(new Payload.Types.Metric
+        {
+            Name = "Missing",
+            Alias = MissingAlias,
+            Datatype = (uint)DataType.Float,
+            IsNull = true,
+        });
+
+        return payload;
+    }
+
+    /// <summary>
+    ///     Builds the NDATA that follows <see cref="BuildNbirth"/>: <c>seq = 1</c> and metrics carrying
+    ///     <b>alias only</b> — no name, no datatype — exactly as a real edge node publishes them.
+    /// </summary>
+    /// <returns>The payload; serialize with <see cref="MessageExtensions.ToByteArray"/>.</returns>
+    public static Payload BuildNdata()
+    {
+        var payload = new Payload
+        {
+            Timestamp = NdataTimestampMs,
+            Seq = 1UL,
+        };
+
+        payload.Metrics.Add(new Payload.Types.Metric
+        {
+            Alias = TemperatureAlias,
+            Timestamp = NdataTimestampMs,
+            FloatValue = 22.25f,
+        });
+
+        payload.Metrics.Add(new Payload.Types.Metric
+        {
+            Alias = CountAlias,
+            IntValue = unchecked((uint)CountDataValue),
+        });
+
+        payload.Metrics.Add(new Payload.Types.Metric
+        {
+            Alias = MissingAlias,
+            IsNull = true,
+        });
+
+        return payload;
+    }
+
+    /// <summary>Reads a committed vector from the test binary's output directory.</summary>
+    /// <param name="fileName"><see cref="NbirthFile"/> or <see cref="NdataFile"/>.</param>
+    /// <returns>The committed wire bytes.</returns>
+    public static byte[] Read(string fileName) => File.ReadAllBytes(PathTo(fileName));
+
+    /// <summary>Resolves a vector's path under the test binary's output directory.</summary>
+    /// <param name="fileName"><see cref="NbirthFile"/> or <see cref="NdataFile"/>.</param>
+    /// <returns>The absolute path.</returns>
+    /// <remarks>
+    ///     Rooted at <see cref="AppContext.BaseDirectory"/> rather than the process working directory:
+    ///     the runner's cwd is not guaranteed to be the output folder, and a relative read that
+    ///     happens to work under one runner is exactly how a fixture stops being copied without
+    ///     anyone noticing.
+    /// </remarks>
+    public static string PathTo(string fileName) =>
+        Path.Combine(AppContext.BaseDirectory, Directory, fileName);
+}

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Tests/SparkplugGoldenVectorTests.cs

@@ -0,0 +1,87 @@
+using System.Runtime.CompilerServices;
+using Google.Protobuf;
+using Shouldly;
+using Xunit;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Tests;
+
+/// <summary>
+///     Guards the committed <c>Golden/*.bin</c> Sparkplug-B wire vectors: they must still be exactly
+///     what <see cref="SparkplugGoldenPayloads"/> produces, and they must actually reach the test
+///     binary's output directory.
+/// </summary>
+/// <remarks>
+///     <para>
+///         Without the drift guard the vectors would be write-once decoration — a re-vendored proto,
+///         a protoc upgrade, or an edited builder could change the encoding while every decode test
+///         kept passing against stale bytes. With it, the committed files are a genuine pin on the
+///         wire format the driver is expected to read.
+///     </para>
+///     <para>
+///         <b>To regenerate</b> (only after a deliberate, reviewed change to the vectors):
+///         <c>OTOPCUA_SPARKPLUG_GOLDEN_REGEN=1 dotnet test tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Tests
+///         --filter "FullyQualifiedName~SparkplugGoldenVectorTests"</c>, then review and commit the
+///         resulting <c>.bin</c> diff.
+///     </para>
+/// </remarks>
+public sealed class SparkplugGoldenVectorTests
+{
+    private const string RegenEnvVar = "OTOPCUA_SPARKPLUG_GOLDEN_REGEN";
+
+    /// <summary>The committed NBIRTH vector is byte-identical to its builder's output.</summary>
+    [Fact]
+    public void Nbirth_CommittedBytes_MatchTheBuilder() =>
+        AssertMatchesBuilder(SparkplugGoldenPayloads.NbirthFile, SparkplugGoldenPayloads.BuildNbirth().ToByteArray());
+
+    /// <summary>The committed NDATA vector is byte-identical to its builder's output.</summary>
+    [Fact]
+    public void Ndata_CommittedBytes_MatchTheBuilder() =>
+        AssertMatchesBuilder(SparkplugGoldenPayloads.NdataFile, SparkplugGoldenPayloads.BuildNdata().ToByteArray());
+
+    /// <summary>
+    ///     Both vectors are present in the test binary's output directory — i.e. the csproj really does
+    ///     copy <c>Golden/**</c>. A missing copy item is invisible in source and turns every decode test
+    ///     into a <see cref="FileNotFoundException"/> at runtime.
+    /// </summary>
+    [Fact]
+    public void GoldenVectors_AreCopiedToTheOutputDirectory()
+    {
+        File.Exists(SparkplugGoldenPayloads.PathTo(SparkplugGoldenPayloads.NbirthFile)).ShouldBeTrue();
+        File.Exists(SparkplugGoldenPayloads.PathTo(SparkplugGoldenPayloads.NdataFile)).ShouldBeTrue();
+    }
+
+    /// <summary>Compares a committed vector to freshly built bytes, regenerating first when asked to.</summary>
+    /// <param name="fileName">The vector's file name.</param>
+    /// <param name="built">The bytes the builder produces now.</param>
+    private static void AssertMatchesBuilder(string fileName, byte[] built)
+    {
+        if (Environment.GetEnvironmentVariable(RegenEnvVar) == "1")
+        {
+            // Write to BOTH the source tree (so the change can be committed) and the output directory
+            // (so the assertion below reads what was just written rather than a stale copied file).
+            var source = Path.Combine(SourceDirectory(), SparkplugGoldenPayloads.Directory, fileName);
+            System.IO.Directory.CreateDirectory(Path.GetDirectoryName(source)!);
+            File.WriteAllBytes(source, built);
+
+            var output = SparkplugGoldenPayloads.PathTo(fileName);
+            System.IO.Directory.CreateDirectory(Path.GetDirectoryName(output)!);
+            File.WriteAllBytes(output, built);
+        }
+
+        var path = SparkplugGoldenPayloads.PathTo(fileName);
+        File.Exists(path).ShouldBeTrue(
+            $"Golden vector '{fileName}' is missing from the output directory. If the csproj copy item is "
+            + $"intact, regenerate with {RegenEnvVar}=1.");
+
+        File.ReadAllBytes(path).ShouldBe(
+            built,
+            $"Golden vector '{fileName}' no longer matches SparkplugGoldenPayloads. Either the builder or "
+            + $"the vendored proto changed. If the change is intended, regenerate with {RegenEnvVar}=1 and "
+            + "commit the .bin diff.");
+    }
+
+    /// <summary>This file's own source directory, resolved at compile time.</summary>
+    /// <param name="path">Supplied by the compiler; never pass it.</param>
+    /// <returns>The directory holding the test sources.</returns>
+    private static string SourceDirectory([CallerFilePath] string path = "") => Path.GetDirectoryName(path)!;
+}

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Tests/ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Tests.csproj

@@ -25,4 +25,11 @@
         <ProjectReference Include="..\..\..\src\Drivers\ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Browser\ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Browser.csproj"/>
     </ItemGroup>
 
+    <!-- The committed Sparkplug-B golden wire vectors. Without this copy item they stay in the source
+         tree and every SparkplugCodecTests read fails with FileNotFoundException at runtime — the
+         failure mode SparkplugGoldenVectorTests.GoldenVectors_AreCopiedToTheOutputDirectory pins. -->
+    <ItemGroup>
+        <None Update="Golden\**\*" CopyToOutputDirectory="PreserveNewest"/>
+    </ItemGroup>
+
 </Project>