fix(tagconfig): close the four #551 residuals — accept-gate-first Inspect, three authoring rules, CSV/service gate, doc sweep

Gitea #551. 1. CSV import ran no driver-typed config gate. Its typed columns were always strictly parsed, but the free-form TagConfigJson column reached the database unread, so a CSV could author a tag the driver rejects — one that deploys green and reads BadNodeIdUnknown forever. RawTagCsvMapper.Parse now names the offending row in the staged review grid, and RawTreeService enforces the same gate on CreateTag/UpdateTag/ImportTags: a form cannot be the guarantee (the API and any future caller reach none of them, and this repo has no bUnit). A rejected import row is an ERROR — the batch inserts nothing and the row is named — never a skip. Note the brief's premise that manual entry rides ImportTagsAsync is wrong: RawManualTagEntryModal commits row-by-row via CreateTagAsync, which is why the gate had to land on all three write paths. 2/3. The seven pre-#549 Inspect methods ran a hand-list of DescribeInvalidEnum checks, so every rejection cause not on the list was invisible. They are now ACCEPT-GATE-FIRST (the MTConnect/Sql/OpcUaClient/Calculation shape): ask the driver's own reader for the verdict, then explain the refusal, with a catch-all so "the parse rejects but Inspect said nothing" is unreachable. That closes S7's absent dataType, AbCip members[], Modbus stringByteOrder and the type-dependent guards, plus causes the issue did not name (absent region/address/tagPath/symbolPath/topic, TwinCAT Structure, MQTT's Sparkplug tuple). FOCAS and MQTT keep advisories about ACCEPTED blobs, so they diagnose rather than return empty. Authoring half: ModbusTagConfigModel gains stringByteOrder; AbCipTagConfigModel asks the new AbCipTagDefinitionFactory.DescribeInvalidMember; S7TagConfigModel captures whether the SOURCE blob declared dataType and asks S7TagDefinitionFactory.DataTypeKey/DeclaresDataType. One authority per rule. 4. Doc sweep: the six factory Inspect summaries, EquipmentTagConfigInspector's class remarks and AdminOperationsActor's comment all claimed invalid enums are "silently defaulted by the lenient runtime" — false since R2-11 Phase C made the runtime reads strict. They describe rejections now.
2026-08-10 00:08:06 -04:00
parent b0d2fa30e3
commit 05b424788f
24 changed files with 1846 additions and 100 deletions
@@ -189,16 +189,34 @@ public static class AbCipTagDefinitionFactory
    }

    /// <summary>
-    ///     Deploy-time inspection (05/CONV-2): warns on a present-but-invalid <c>dataType</c> (silently
-    ///     defaulted by the lenient runtime) and on a structurally unparseable TagConfig. Empty when clean
-    ///     or not an equipment-tag object. Never throws.
+    ///     The RawPath handed to <see cref="FromTagConfig"/> during inspection — the mapper only copies it
+    ///     onto <see cref="AbCipTagDefinition.Name"/> and never validates it.
    /// </summary>
+    private const string InspectionRawPath = "(inspect)";
+
+    /// <summary>
+    ///     Deploy-time inspection (05/CONV-2): warns for a blob <see cref="FromTagConfig"/> would
+    ///     <b>reject</b> — a structurally unparseable or non-object document, an absent / non-string /
+    ///     blank <c>tagPath</c>, a present-but-invalid <c>dataType</c> (the runtime enum read is STRICT
+    ///     since R2-11 Phase C, so a typo rejects the tag), or a malformed declared UDT member (see
+    ///     <see cref="DescribeInvalidMember(JsonElement)"/>). Such a tag is skipped by the driver and reads
+    ///     <c>BadNodeIdUnknown</c> forever. Empty when the mapper accepts the blob, when it is blank, or
+    ///     when it is not an equipment-tag object. Never throws.
+    /// </summary>
+    /// <remarks>
+    ///     <b>The verdict comes from <see cref="FromTagConfig"/>, not from a mirror</b> (Gitea #551) — see
+    ///     <c>ModbusTagDefinitionFactory.Inspect</c>'s remarks for the full argument.
+    /// </remarks>
    /// <param name="reference">The equipment tag's TagConfig JSON.</param>
    /// <returns>The warnings; empty when clean.</returns>
    public static IReadOnlyList<string> Inspect(string reference)
    {
        var warnings = new List<string>();
        if (string.IsNullOrWhiteSpace(reference) || reference[0] != '{') return warnings;
+
+        // The accept gate: whatever the driver reads draws nothing.
+        if (FromTagConfig(reference, InspectionRawPath, out _)) return warnings;
+
        try
        {
            using var doc = JsonDocument.Parse(reference);
@@ -208,16 +226,129 @@ public static class AbCipTagDefinitionFactory
                warnings.Add("AbCip TagConfig root is not a JSON object — the tag will not resolve (BadNodeIdUnknown).");
                return warnings;
            }
-            var w = TagConfigJson.DescribeInvalidEnum<AbCipDataType>(root, "dataType");
-            if (w is not null) warnings.Add(w);
+
+            DescribeRejection(root, warnings);
        }
        catch (JsonException)
        {
            warnings.Add("AbCip TagConfig is not valid JSON — the tag will not resolve (BadNodeIdUnknown).");
+            return warnings;
        }
+
+        if (warnings.Count == 0)
+        {
+            warnings.Add(
+                "AbCip TagConfig was rejected by the driver's tag reader — the driver will skip this tag "
+                + "and it will read BadNodeIdUnknown.");
+        }
+
        return warnings;
    }

+    /// <summary>
+    ///     Explains why <see cref="FromTagConfig"/> refused an object-rooted blob, walking its checks in the
+    ///     same order. Runs only after the mapper has already refused, so it can never invent strictness.
+    /// </summary>
+    /// <param name="root">The TagConfig root object.</param>
+    /// <param name="warnings">The list to append warnings to.</param>
+    private static void DescribeRejection(JsonElement root, List<string> warnings)
+    {
+        if (!root.TryGetProperty("tagPath", out var tagPathEl) || tagPathEl.ValueKind != JsonValueKind.String)
+        {
+            warnings.Add(
+                "AbCip TagConfig has no string 'tagPath' — AbCip is a symbolic driver and addresses by "
+                + "Logix tag path, so the driver will skip this tag and it will read BadNodeIdUnknown.");
+        }
+        else if (string.IsNullOrWhiteSpace(tagPathEl.GetString()))
+        {
+            warnings.Add("AbCip TagConfig has a blank 'tagPath' — the tag will not resolve (BadNodeIdUnknown).");
+        }
+
+        if (TagConfigJson.DescribeInvalidEnum<AbCipDataType>(root, "dataType") is { } w) warnings.Add(w);
+
+        if (DescribeInvalidMember(root) is { } memberWarning) warnings.Add(memberWarning);
+    }
+
+    /// <summary>
+    ///     <b>The single authority on the declared-UDT-member rules</b>, consulted by <see cref="Inspect"/>
+    ///     and by the AdminUI's <c>AbCipTagConfigModel.Validate</c> alike. Describes the FIRST malformed
+    ///     entry of the optional <c>members</c> array — a non-object entry, one with no usable <c>name</c>,
+    ///     or one whose <c>dataType</c> is a present-but-invalid <see cref="AbCipDataType"/> — or
+    ///     <see langword="null"/> when every member reads.
+    ///     <para>
+    ///         The member rules are as strict as the top-level ones (<see cref="FromTagConfig"/> refuses the
+    ///         WHOLE tag for one bad member), but no authoring surface checked them: the typed editor emits
+    ///         only <c>tagPath</c>/<c>dataType</c>/<c>writable</c> and <c>members</c> rides the model's
+    ///         preserved key bag untouched, so a hand-authored / CSV / API blob with a typo'd member
+    ///         deployed clean and died at the driver — Gitea #551 item 3.
+    ///     </para>
+    ///     <para>
+    ///         A <c>members</c> value that is absent or not a JSON array draws nothing: the mapper reads it
+    ///         only when it is an array, and an array of zero usable members simply means "no member
+    ///         fan-out". Saying otherwise here would make the gate stricter than the reader.
+    ///     </para>
+    /// </summary>
+    /// <param name="root">The TagConfig root object.</param>
+    /// <returns>The warning text, or <see langword="null"/> when the members read.</returns>
+    public static string? DescribeInvalidMember(JsonElement root)
+    {
+        if (!root.TryGetProperty("members", out var membersEl) || membersEl.ValueKind != JsonValueKind.Array)
+            return null;
+
+        var index = 0;
+        foreach (var member in membersEl.EnumerateArray())
+        {
+            var label = $"members[{index}]";
+            index++;
+
+            if (member.ValueKind != JsonValueKind.Object)
+            {
+                return $"AbCip {label} is not a JSON object — a declared UDT member needs a 'name' and may "
+                       + "carry a 'dataType'; the WHOLE tag is rejected (BadNodeIdUnknown).";
+            }
+
+            if (!member.TryGetProperty("name", out var nameEl)
+                || nameEl.ValueKind != JsonValueKind.String
+                || string.IsNullOrWhiteSpace(nameEl.GetString()))
+            {
+                return $"AbCip {label} has no usable 'name' — a declared UDT member must name itself; the "
+                       + "WHOLE tag is rejected (BadNodeIdUnknown).";
+            }
+
+            if (TagConfigJson.DescribeInvalidEnum<AbCipDataType>(member, "dataType") is { } dataTypeWarning)
+            {
+                return $"AbCip {label}: {dataTypeWarning} — the WHOLE tag is rejected (BadNodeIdUnknown).";
+            }
+        }
+
+        return null;
+    }
+
+    /// <summary>
+    ///     String-input overload of <see cref="DescribeInvalidMember(JsonElement)"/>, for the AdminUI
+    ///     authoring model — which holds a mutable <c>JsonObject</c> key bag rather than a
+    ///     <see cref="JsonElement"/> and so reaches the same rule through a different door. Never throws: a
+    ///     blank / unparseable / non-object blob draws nothing here, because those shapes are the OTHER
+    ///     gates' business, not the member rule's.
+    /// </summary>
+    /// <param name="tagConfig">The authored equipment-tag TagConfig JSON.</param>
+    /// <returns>The warning text, or <see langword="null"/> when the members read.</returns>
+    public static string? DescribeInvalidMember(string? tagConfig)
+    {
+        if (string.IsNullOrWhiteSpace(tagConfig)) return null;
+        try
+        {
+            using var doc = JsonDocument.Parse(tagConfig);
+            return doc.RootElement.ValueKind == JsonValueKind.Object
+                ? DescribeInvalidMember(doc.RootElement)
+                : null;
+        }
+        catch (JsonException)
+        {
+            return null;
+        }
+    }
+
    private static bool ReadBool(JsonElement o, string name)
        => o.TryGetProperty(name, out var e) && e.ValueKind == JsonValueKind.True;

@@ -119,16 +119,40 @@ public static class AbLegacyTagDefinitionFactory
    }

    /// <summary>
-    ///     Deploy-time inspection (05/CONV-2): warns on a present-but-invalid <c>dataType</c> (silently
-    ///     defaulted by the lenient runtime) and on a structurally unparseable TagConfig. Empty when clean
-    ///     or not an equipment-tag object. Never throws.
+    ///     The RawPath handed to <see cref="FromTagConfig"/> during inspection — the mapper only copies it
+    ///     onto <see cref="AbLegacyTagDefinition.Name"/> and never validates it.
    /// </summary>
+    private const string InspectionRawPath = "(inspect)";
+
+    /// <summary>
+    ///     Deploy-time inspection (05/CONV-2): warns for a blob <see cref="FromTagConfig"/> would
+    ///     <b>reject</b> — a structurally unparseable or non-object document, an absent / non-string /
+    ///     blank <c>address</c>, or a present-but-invalid <c>dataType</c> (the runtime enum read is STRICT
+    ///     since R2-11 Phase C, so a typo rejects the tag). Such a tag is skipped by the driver and reads
+    ///     <c>BadNodeIdUnknown</c> forever. Empty when the mapper accepts the blob, when it is blank, or
+    ///     when it is not an equipment-tag object. Never throws.
+    /// </summary>
+    /// <remarks>
+    ///     <b>The verdict comes from <see cref="FromTagConfig"/>, not from a mirror</b> (Gitea #551) — see
+    ///     <c>ModbusTagDefinitionFactory.Inspect</c>'s remarks for the full argument.
+    ///     <para>
+    ///         An <c>arrayLength</c> above <see cref="AbLegacyArray.MaxElements"/> is deliberately NOT
+    ///         warned about: the mapper CLAMPS it rather than rejecting, so the driver serves the tag. The
+    ///         AdminUI model refuses it at authoring because the un-clamped length also sets the OPC UA
+    ///         <c>ArrayDimensions</c>; a warning here could be promoted to a deploy ERROR and would then
+    ///         block a tag the runtime happily reads.
+    ///     </para>
+    /// </remarks>
    /// <param name="reference">The equipment tag's TagConfig JSON.</param>
    /// <returns>The warnings; empty when clean.</returns>
    public static IReadOnlyList<string> Inspect(string reference)
    {
        var warnings = new List<string>();
        if (string.IsNullOrWhiteSpace(reference) || reference[0] != '{') return warnings;
+
+        // The accept gate: whatever the driver reads draws nothing.
+        if (FromTagConfig(reference, InspectionRawPath, out _)) return warnings;
+
        try
        {
            using var doc = JsonDocument.Parse(reference);
@@ -138,16 +162,47 @@ public static class AbLegacyTagDefinitionFactory
                warnings.Add("AbLegacy TagConfig root is not a JSON object — the tag will not resolve (BadNodeIdUnknown).");
                return warnings;
            }
-            var w = TagConfigJson.DescribeInvalidEnum<AbLegacyDataType>(root, "dataType");
-            if (w is not null) warnings.Add(w);
+
+            DescribeRejection(root, warnings);
        }
        catch (JsonException)
        {
            warnings.Add("AbLegacy TagConfig is not valid JSON — the tag will not resolve (BadNodeIdUnknown).");
+            return warnings;
        }
+
+        if (warnings.Count == 0)
+        {
+            warnings.Add(
+                "AbLegacy TagConfig was rejected by the driver's tag reader — the driver will skip this tag "
+                + "and it will read BadNodeIdUnknown.");
+        }
+
        return warnings;
    }

+    /// <summary>
+    ///     Explains why <see cref="FromTagConfig"/> refused an object-rooted blob, walking its checks in the
+    ///     same order. Runs only after the mapper has already refused, so it can never invent strictness.
+    /// </summary>
+    /// <param name="root">The TagConfig root object.</param>
+    /// <param name="warnings">The list to append warnings to.</param>
+    private static void DescribeRejection(JsonElement root, List<string> warnings)
+    {
+        if (!root.TryGetProperty("address", out var addr) || addr.ValueKind != JsonValueKind.String)
+        {
+            warnings.Add(
+                "AbLegacy TagConfig has no string 'address' (e.g. N7:0, B3:1/2, F8:5) — the driver will "
+                + "skip this tag and it will read BadNodeIdUnknown.");
+        }
+        else if (string.IsNullOrWhiteSpace(addr.GetString()))
+        {
+            warnings.Add("AbLegacy TagConfig has a blank 'address' — the tag will not resolve (BadNodeIdUnknown).");
+        }
+
+        if (TagConfigJson.DescribeInvalidEnum<AbLegacyDataType>(root, "dataType") is { } w) warnings.Add(w);
+    }
+
    private static int ReadInt(JsonElement o, string name)
        => o.TryGetProperty(name, out var e) && e.ValueKind == JsonValueKind.Number
           && e.TryGetInt32(out var v) ? v : 0;
@@ -95,10 +95,33 @@ public static class FocasTagDefinitionFactory
    }

    /// <summary>
-    ///     Deploy-time inspection (05/CONV-2, 05/UNDER-1): warns on a present-but-invalid <c>dataType</c>
-    ///     (silently defaulted by the lenient runtime), on an authored <c>writable:true</c> (the FOCAS wire
-    ///     is read-only — <c>WriteAsync</c> always returns <c>BadNotWritable</c>), and on a structurally
-    ///     unparseable TagConfig. Empty when clean or not an equipment-tag object. Never throws.
+    ///     The RawPath handed to <see cref="FromTagConfig"/> during inspection — the mapper only copies it
+    ///     onto <see cref="FocasTagDefinition.Name"/> and never validates it.
+    /// </summary>
+    private const string InspectionRawPath = "(inspect)";
+
+    /// <summary>
+    ///     Deploy-time inspection (05/CONV-2, 05/UNDER-1). Two kinds of warning, and the distinction is
+    ///     load-bearing:
+    ///     <list type="bullet">
+    ///         <item>
+    ///             <b>Rejections</b> — a blob <see cref="FromTagConfig"/> would refuse: an unparseable or
+    ///             non-object document, an absent / non-string / blank <c>address</c>, or a
+    ///             present-but-invalid <c>dataType</c> (the runtime enum read is STRICT since R2-11 Phase C,
+    ///             so a typo rejects the tag). The driver skips such a tag and it reads
+    ///             <c>BadNodeIdUnknown</c> forever. These are diagnosed only when the mapper has actually
+    ///             refused, so this gate can never be stricter than the runtime (Gitea #551).
+    ///         </item>
+    ///         <item>
+    ///             <b>Advisories</b> — an <em>accepted</em> blob that still will not work: an unparseable
+    ///             FOCAS address (#540; the mapper only requires a non-blank string, the driver's own init
+    ///             then drops it) and an authored <c>writable:true</c> (the FOCAS wire is read-only, so
+    ///             <c>WriteAsync</c> always returns <c>BadNotWritable</c>). These run whether or not the
+    ///             blob parses, which is why FOCAS does not simply return empty on accept.
+    ///         </item>
+    ///     </list>
+    ///     Empty for a clean, accepted blob, for a blank one, or for one that is not an equipment-tag
+    ///     object. Never throws.
    /// </summary>
    /// <param name="reference">The equipment tag's TagConfig JSON.</param>
    /// <returns>The warnings; empty when clean.</returns>
@@ -106,6 +129,11 @@ public static class FocasTagDefinitionFactory
    {
        var warnings = new List<string>();
        if (string.IsNullOrWhiteSpace(reference) || reference[0] != '{') return warnings;
+
+        // The accept gate: only a blob the driver REFUSES gets a rejection diagnosis. The advisories below
+        // apply either way — see the summary.
+        var accepted = FromTagConfig(reference, InspectionRawPath, out _);
+
        try
        {
            using var doc = JsonDocument.Parse(reference);
@@ -115,30 +143,72 @@ public static class FocasTagDefinitionFactory
                warnings.Add("FOCAS TagConfig root is not a JSON object — the tag will not resolve (BadNodeIdUnknown).");
                return warnings;
            }
-            var w = TagConfigJson.DescribeInvalidEnum<FocasDataType>(root, "dataType");
-            if (w is not null) warnings.Add(w);
-            // Gitea #540: an address the driver cannot parse is skipped at init and reads
-            // BadNodeIdUnknown forever, while driver health stays Healthy with zero errors. The
-            // AdminUI modal rejects it outright; this covers the paths that never touch the modal
-            // (CSV import, the API) by at least surfacing it on the deployment.
-            if (root.TryGetProperty("address", out var addr)
-                && addr.ValueKind == JsonValueKind.String
-                && addr.GetString() is { } address
-                && !string.IsNullOrWhiteSpace(address)
-                && FocasAddress.TryParse(address) is null)
-            {
-                warnings.Add(
-                    $"FOCAS address '{address.Trim()}' is not parseable (expected X0.0 / R100, " +
-                    "PARAM:1020, MACRO:500 or FIXED:Identity/SeriesNumber) — the driver will skip " +
-                    "this tag at startup and it will read BadNodeIdUnknown.");
-            }
-            if (root.TryGetProperty("writable", out var wr) && wr.ValueKind == JsonValueKind.True)
-                warnings.Add("FOCAS wire is read-only — an authored 'writable:true' still fails at the wire with BadNotWritable.");
+
+            if (!accepted) DescribeRejection(root, warnings);
+            DescribeAdvisories(root, warnings);
        }
        catch (JsonException)
        {
            warnings.Add("FOCAS TagConfig is not valid JSON — the tag will not resolve (BadNodeIdUnknown).");
+            return warnings;
        }
+
+        if (!accepted && warnings.Count == 0)
+        {
+            warnings.Add(
+                "FOCAS TagConfig was rejected by the driver's tag reader — the driver will skip this tag "
+                + "and it will read BadNodeIdUnknown.");
+        }
+
        return warnings;
    }
+
+    /// <summary>
+    ///     Explains why <see cref="FromTagConfig"/> refused an object-rooted blob, walking its checks in the
+    ///     same order. Runs only after the mapper has already refused, so it can never invent strictness.
+    /// </summary>
+    /// <param name="root">The TagConfig root object.</param>
+    /// <param name="warnings">The list to append warnings to.</param>
+    private static void DescribeRejection(JsonElement root, List<string> warnings)
+    {
+        if (!root.TryGetProperty("address", out var addr) || addr.ValueKind != JsonValueKind.String)
+        {
+            warnings.Add(
+                "FOCAS TagConfig has no string 'address' — the driver will skip this tag and it will read "
+                + "BadNodeIdUnknown.");
+        }
+        else if (string.IsNullOrWhiteSpace(addr.GetString()))
+        {
+            warnings.Add("FOCAS TagConfig has a blank 'address' — the tag will not resolve (BadNodeIdUnknown).");
+        }
+
+        if (TagConfigJson.DescribeInvalidEnum<FocasDataType>(root, "dataType") is { } w) warnings.Add(w);
+    }
+
+    /// <summary>
+    ///     Warnings about a blob the mapper ACCEPTS but the driver still cannot serve as authored — see the
+    ///     "advisories" bullet on <see cref="Inspect"/>.
+    /// </summary>
+    /// <param name="root">The TagConfig root object.</param>
+    /// <param name="warnings">The list to append warnings to.</param>
+    private static void DescribeAdvisories(JsonElement root, List<string> warnings)
+    {
+        // Gitea #540: an address the driver cannot parse is skipped at init and reads BadNodeIdUnknown
+        // forever, while driver health stays Healthy with zero errors. The AdminUI modal rejects it
+        // outright; this covers the paths that never touch the modal (CSV import, the API).
+        if (root.TryGetProperty("address", out var addr)
+            && addr.ValueKind == JsonValueKind.String
+            && addr.GetString() is { } address
+            && !string.IsNullOrWhiteSpace(address)
+            && FocasAddress.TryParse(address) is null)
+        {
+            warnings.Add(
+                $"FOCAS address '{address.Trim()}' is not parseable (expected X0.0 / R100, " +
+                "PARAM:1020, MACRO:500 or FIXED:Identity/SeriesNumber) — the driver will skip " +
+                "this tag at startup and it will read BadNodeIdUnknown.");
+        }
+
+        if (root.TryGetProperty("writable", out var wr) && wr.ValueKind == JsonValueKind.True)
+            warnings.Add("FOCAS wire is read-only — an authored 'writable:true' still fails at the wire with BadNotWritable.");
+    }
 }
@@ -130,18 +130,41 @@ public static class ModbusTagDefinitionFactory
    }

    /// <summary>
-    ///     Deploy-time inspection of an equipment-tag <c>TagConfig</c> blob (05/CONV-2). Returns
-    ///     human-readable warnings for present-but-invalid enum values (<c>region</c> / <c>dataType</c> /
-    ///     <c>byteOrder</c> — which the lenient runtime silently defaults) and for a structurally
-    ///     unparseable TagConfig (which the runtime turns into a silent <c>BadNodeIdUnknown</c>). Empty when
-    ///     the blob is clean or is not an equipment-tag TagConfig object. Never throws.
+    ///     The RawPath handed to <see cref="FromTagConfig"/> during inspection. The mapper only copies it
+    ///     onto <see cref="ModbusTagDefinition.Name"/> and never validates it, so inspection is free to pass
+    ///     a placeholder — the deploy gate is inspecting a blob, not a placed tag.
    /// </summary>
+    private const string InspectionRawPath = "(inspect)";
+
+    /// <summary>
+    ///     Deploy-time inspection of an equipment-tag <c>TagConfig</c> blob (05/CONV-2). Returns
+    ///     human-readable warnings for a blob <see cref="FromTagConfig"/> would <b>reject</b> — a
+    ///     structurally unparseable or non-object document, an absent <c>region</c>, an absent or
+    ///     out-of-range <c>address</c>, a present-but-invalid <c>region</c> / <c>dataType</c> /
+    ///     <c>byteOrder</c> / <c>stringByteOrder</c> (each rejects the tag: the runtime enum reads are
+    ///     STRICT since R2-11 Phase C), or a type-dependent guard (<c>String</c> with no
+    ///     <c>stringLength</c>, <c>BitInRegister</c> with a <c>bitIndex</c> outside 0–15). Such a tag is
+    ///     skipped by the driver and reads <c>BadNodeIdUnknown</c> forever. Empty when the mapper accepts
+    ///     the blob, when it is blank, or when it is not an equipment-tag TagConfig object. Never throws.
+    /// </summary>
+    /// <remarks>
+    ///     <b>The verdict comes from <see cref="FromTagConfig"/>, not from a mirror</b> (Gitea #551). The
+    ///     rule this gate must never break is being stricter than the runtime — a blob the driver serves
+    ///     must not draw a warning calling it invalid — and running the mapper first makes that structural
+    ///     rather than a promise. It also closes the opposite gap: the previous hand-list of enum checks
+    ///     was silent for every rejection cause that was not on it (an absent <c>region</c>, a bad
+    ///     <c>address</c>, <c>stringByteOrder</c>), so a tag the driver refuses deployed clean.
+    /// </remarks>
    /// <param name="reference">The equipment tag's TagConfig JSON.</param>
    /// <returns>The warnings; empty when clean.</returns>
    public static IReadOnlyList<string> Inspect(string reference)
    {
        var warnings = new List<string>();
        if (string.IsNullOrWhiteSpace(reference) || reference[0] != '{') return warnings;
+
+        // The accept gate: whatever the driver reads draws nothing. See the remarks.
+        if (FromTagConfig(reference, InspectionRawPath, out _)) return warnings;
+
        try
        {
            using var doc = JsonDocument.Parse(reference);
@@ -151,23 +174,90 @@ public static class ModbusTagDefinitionFactory
                warnings.Add("Modbus TagConfig root is not a JSON object — the tag will not resolve (BadNodeIdUnknown).");
                return warnings;
            }
-            foreach (var w in new[]
-            {
-                TagConfigJson.DescribeInvalidEnum<ModbusRegion>(root, "region"),
-                TagConfigJson.DescribeInvalidEnum<ModbusDataType>(root, "dataType"),
-                TagConfigJson.DescribeInvalidEnum<ModbusByteOrder>(root, "byteOrder"),
-            })
-            {
-                if (w is not null) warnings.Add(w);
-            }
+
+            DescribeRejection(root, warnings);
        }
        catch (JsonException)
        {
            warnings.Add("Modbus TagConfig is not valid JSON — the tag will not resolve (BadNodeIdUnknown).");
+            return warnings;
        }
+
+        // Backstop: the mapper refused for a reason nothing above names (it also swallows FormatException
+        // and InvalidOperationException). Saying so beats reporting a clean blob the driver will skip.
+        if (warnings.Count == 0)
+        {
+            warnings.Add(
+                "Modbus TagConfig was rejected by the driver's tag reader — the driver will skip this tag "
+                + "and it will read BadNodeIdUnknown.");
+        }
+
        return warnings;
    }

+    /// <summary>
+    ///     Explains why <see cref="FromTagConfig"/> refused an object-rooted blob, walking its checks in the
+    ///     same order. Every branch mirrors a <c>return false</c> there — and it runs only after the mapper
+    ///     has already refused, so it can never invent strictness of its own.
+    /// </summary>
+    /// <param name="root">The TagConfig root object.</param>
+    /// <param name="warnings">The list to append warnings to.</param>
+    private static void DescribeRejection(JsonElement root, List<string> warnings)
+    {
+        if (!root.TryGetProperty("region", out _))
+        {
+            warnings.Add(
+                "Modbus TagConfig has no 'region' — every Modbus tag must name one (valid: "
+                + string.Join(", ", Enum.GetNames<ModbusRegion>())
+                + "); the driver will skip this tag and it will read BadNodeIdUnknown.");
+        }
+
+        if (!root.TryGetProperty("address", out var addr))
+        {
+            warnings.Add("Modbus TagConfig has no 'address' — the tag will not resolve (BadNodeIdUnknown).");
+        }
+        else if (addr.ValueKind != JsonValueKind.Number
+                 || !addr.TryGetInt32(out var address)
+                 || address < 0 || address > ushort.MaxValue)
+        {
+            warnings.Add(
+                $"value '{addr.GetRawText()}' for 'address' is not a Modbus register address (an integer "
+                + $"0–{ushort.MaxValue}); the tag will not resolve (BadNodeIdUnknown).");
+        }
+
+        // Strict enums, in the order FromTagConfig reads them. stringByteOrder is read as strictly as its
+        // three siblings, and was the one the previous hand-list forgot (Gitea #551).
+        foreach (var w in new[]
+        {
+            TagConfigJson.DescribeInvalidEnum<ModbusRegion>(root, "region"),
+            TagConfigJson.DescribeInvalidEnum<ModbusDataType>(root, "dataType"),
+            TagConfigJson.DescribeInvalidEnum<ModbusByteOrder>(root, "byteOrder"),
+            TagConfigJson.DescribeInvalidEnum<ModbusStringByteOrder>(root, "stringByteOrder"),
+        })
+        {
+            if (w is not null) warnings.Add(w);
+        }
+
+        // Type-dependent guards. The byte/ushort NARROWING is part of the rule, not an accident of the
+        // mapper: it reads `(byte)bitIndex` / `(ushort)stringLength`, so 256 is bit 0 and is ACCEPTED.
+        // Describing the un-narrowed value here would call a blob invalid that the driver serves.
+        if (!TagConfigJson.TryReadEnumStrict(root, "dataType", ModbusDataType.Int16, out var dataType)) return;
+
+        if (dataType == ModbusDataType.String && (ushort)ReadInt(root, "stringLength") < 1)
+        {
+            warnings.Add(
+                "Modbus String tag has no 'stringLength' of at least 1 — a zero-length string reads zero "
+                + "registers, which is an illegal Modbus request, so the tag is rejected (BadNodeIdUnknown).");
+        }
+
+        if (dataType == ModbusDataType.BitInRegister && (byte)ReadInt(root, "bitIndex") > 15)
+        {
+            warnings.Add(
+                "Modbus BitInRegister tag has a 'bitIndex' outside 0–15 — the bit mask would overflow a "
+                + "16-bit register, so the tag is rejected (BadNodeIdUnknown).");
+        }
+    }
+
    private static int ReadInt(JsonElement o, string name)
        => o.TryGetProperty(name, out var e) && e.ValueKind == JsonValueKind.Number
           && e.TryGetInt32(out var v) ? v : 0;
@@ -205,19 +205,46 @@ public static class MqttTagDefinitionFactory
    }

    /// <summary>
-    ///     Deploy-time inspection of an equipment-tag <c>TagConfig</c> blob. Returns human-readable
-    ///     warnings for a structurally unparseable blob (which the runtime turns into a silent
-    ///     <c>BadNodeIdUnknown</c>), for present-but-invalid <c>payloadFormat</c> / <c>dataType</c> /
-    ///     <c>qos</c> values, and for a <b>wildcard</b> tag topic (a tag bound to <c>+</c> / <c>#</c>
-    ///     would receive values from many topics — ambiguous, and almost never what the operator meant).
-    ///     Empty when the blob is clean or is not an equipment-tag TagConfig object. Never throws.
+    ///     The RawPath handed to the mappers during inspection — they only copy it onto
+    ///     <see cref="MqttTagDefinition.Name"/> and never validate it.
    /// </summary>
+    private const string InspectionRawPath = "(inspect)";
+
+    /// <summary>
+    ///     Deploy-time inspection of an equipment-tag <c>TagConfig</c> blob. Two kinds of warning:
+    ///     <list type="bullet">
+    ///         <item>
+    ///             <b>Rejections</b> — a blob NEITHER runtime mapper would read: an unparseable or
+    ///             non-object document, present-but-invalid <c>payloadFormat</c> / <c>dataType</c> /
+    ///             <c>qos</c> values (all read strictly), or an address that names neither a Plain
+    ///             <c>topic</c> nor a complete Sparkplug <c>groupId</c>/<c>edgeNodeId</c>/<c>metricName</c>
+    ///             tuple. Such a tag is skipped by the driver and reads <c>BadNodeIdUnknown</c> forever.
+    ///         </item>
+    ///         <item>
+    ///             <b>Advisory</b> — a <b>wildcard</b> tag topic (<c>+</c> / <c>#</c>). The mapper
+    ///             deliberately ACCEPTS it (ambiguous, not unparseable), so this runs either way.
+    ///         </item>
+    ///     </list>
+    ///     Empty for a clean, readable blob, for a blank one, or for one that is not an equipment-tag
+    ///     TagConfig object. Never throws.
+    /// </summary>
+    /// <remarks>
+    ///     <b>The accept gate is the UNION of the two mappers</b> (Gitea #551), because <c>Inspect</c> is
+    ///     handed a blob with no mode: the driver's <see cref="MqttMode"/> decides which of
+    ///     <see cref="FromTagConfig"/> / <see cref="FromSparkplugTagConfig"/> reads it, and nothing about a
+    ///     tag row says which. Gating on the Plain mapper alone would warn that every correctly-authored
+    ///     Sparkplug tag has no topic — a gate stricter than the runtime, the one thing it must never be.
+    /// </remarks>
    /// <param name="reference">The equipment tag's TagConfig JSON.</param>
    /// <returns>The warnings; empty when clean.</returns>
    public static IReadOnlyList<string> Inspect(string reference)
    {
        var warnings = new List<string>();
        if (string.IsNullOrWhiteSpace(reference) || reference[0] != '{') return warnings;
+
+        var accepted = FromTagConfig(reference, InspectionRawPath, out _)
+                       || FromSparkplugTagConfig(reference, InspectionRawPath, out _);
+
        try
        {
            using var doc = JsonDocument.Parse(reference);
@@ -227,16 +254,11 @@ public static class MqttTagDefinitionFactory
                warnings.Add("Mqtt TagConfig root is not a JSON object — the tag will not resolve (BadNodeIdUnknown).");
                return warnings;
            }
-            foreach (var w in new[]
-            {
-                TagConfigJson.DescribeInvalidEnum<MqttPayloadFormat>(root, "payloadFormat"),
-                TagConfigJson.DescribeInvalidEnum<DriverDataType>(root, "dataType"),
-                DescribeInvalidQos(root),
-            })
-            {
-                if (w is not null) warnings.Add(w);
-            }
-            var topic = ReadString(root, "topic");
+
+            if (!accepted) DescribeRejection(root, warnings);
+
+            // Advisory — the mappers accept a wildcard topic on purpose; see the summary.
+            var topic = ReadString(root, MqttTagConfigKeys.Topic);
            if (topic.IndexOfAny(TopicWildcards) >= 0)
            {
                warnings.Add(
@@ -247,10 +269,53 @@ public static class MqttTagDefinitionFactory
        catch (JsonException)
        {
            warnings.Add("Mqtt TagConfig is not valid JSON — the tag will not resolve (BadNodeIdUnknown).");
+            return warnings;
        }
+
+        if (!accepted && warnings.Count == 0)
+        {
+            warnings.Add(
+                "Mqtt TagConfig was rejected by the driver's tag reader — the driver will skip this tag "
+                + "and it will read BadNodeIdUnknown.");
+        }
+
        return warnings;
    }

+    /// <summary>
+    ///     Explains why BOTH mappers refused an object-rooted blob. The strict-field checks are shared by
+    ///     the two shapes; the address check names what each shape needed. Runs only after both mappers have
+    ///     already refused, so it can never invent strictness.
+    /// </summary>
+    /// <param name="root">The TagConfig root object.</param>
+    /// <param name="warnings">The list to append warnings to.</param>
+    private static void DescribeRejection(JsonElement root, List<string> warnings)
+    {
+        foreach (var w in new[]
+        {
+            TagConfigJson.DescribeInvalidEnum<MqttPayloadFormat>(root, "payloadFormat"),
+            TagConfigJson.DescribeInvalidEnum<DriverDataType>(root, "dataType"),
+            DescribeInvalidQos(root),
+        })
+        {
+            if (w is not null) warnings.Add(w);
+        }
+
+        // Address: Plain needs a topic, Sparkplug needs the whole binding tuple. Neither is satisfied, or
+        // one of the strict fields above already refused both — only say it when the address is the cause.
+        var hasTopic = !string.IsNullOrWhiteSpace(ReadString(root, MqttTagConfigKeys.Topic));
+        var hasSparkplugTuple = !string.IsNullOrWhiteSpace(ReadString(root, MqttTagConfigKeys.GroupId))
+                                && !string.IsNullOrWhiteSpace(ReadString(root, MqttTagConfigKeys.EdgeNodeId))
+                                && !string.IsNullOrWhiteSpace(ReadString(root, MqttTagConfigKeys.MetricName));
+        if (!hasTopic && !hasSparkplugTuple)
+        {
+            warnings.Add(
+                "Mqtt TagConfig names no address — a Plain-mode tag needs a 'topic', a Sparkplug B tag "
+                + "needs 'groupId' + 'edgeNodeId' + 'metricName'. The driver will skip this tag and it "
+                + "will read BadNodeIdUnknown.");
+        }
+    }
+
    /// <summary>
    ///     Strict <c>qos</c> read, mirroring <see cref="TagConfigJson.TryReadEnumStrict{TEnum}"/>'s
    ///     absent / valid / present-but-invalid split: absent ⇒ <see langword="null"/> (the driver-level
@@ -111,16 +111,61 @@ public static class S7TagDefinitionFactory
    }

    /// <summary>
-    ///     Deploy-time inspection (05/CONV-2): warns on a present-but-invalid <c>dataType</c> (silently
-    ///     defaulted by the lenient runtime) and on a structurally unparseable TagConfig (a silent
-    ///     <c>BadNodeIdUnknown</c> at runtime). Empty when clean or not an equipment-tag object. Never throws.
+    ///     The <c>TagConfig</c> key carrying the S7 data type. Shared with the AdminUI authoring model so
+    ///     "does the blob declare a type?" is asked of one spelling, not two (Gitea #551).
    /// </summary>
+    public const string DataTypeKey = "dataType";
+
+    /// <summary>
+    ///     The RawPath handed to <see cref="FromTagConfig"/> during inspection — the mapper only copies it
+    ///     onto <see cref="S7TagDefinition.Name"/> and never validates it.
+    /// </summary>
+    private const string InspectionRawPath = "(inspect)";
+
+    /// <summary>
+    ///     <b>The single authority on whether an S7 blob DECLARES a data type</b>, consulted by
+    ///     <see cref="Inspect"/> and by the AdminUI's <c>S7TagConfigModel.Validate</c> alike.
+    ///     <para>
+    ///         S7 is the one driver in the fleet whose reader <b>requires the key to be present</b>
+    ///         (<see cref="FromTagConfig"/> refuses a blob without it, where every sibling falls back to a
+    ///         default), so a hand-authored / CSV / API blob that omits it used to pass both gates and die
+    ///         at the driver with <c>BadNodeIdUnknown</c> — Gitea #551 item 2.
+    ///     </para>
+    ///     <para>
+    ///         Presence is judged on the KEY, not on the value: a non-string token
+    ///         (<c>"dataType": 8</c>) satisfies the presence check and is then treated as absent by
+    ///         <see cref="TagConfigJson.TryReadEnumStrict{TEnum}"/>, so the blob is ACCEPTED as
+    ///         <see cref="S7DataType.Int16"/>. Judging the value here would make this gate stricter than
+    ///         the reader.
+    ///     </para>
+    /// </summary>
+    /// <param name="root">The TagConfig root object.</param>
+    /// <returns><see langword="true"/> when the blob carries a <c>dataType</c> key of any kind.</returns>
+    public static bool DeclaresDataType(JsonElement root) => root.TryGetProperty(DataTypeKey, out _);
+
+    /// <summary>
+    ///     Deploy-time inspection (05/CONV-2): warns for a blob <see cref="FromTagConfig"/> would
+    ///     <b>reject</b> — a structurally unparseable or non-object document, an absent / non-string /
+    ///     blank <c>address</c>, an <b>absent</b> <c>dataType</c> (see <see cref="DeclaresDataType"/>), a
+    ///     present-but-invalid <c>dataType</c> (the runtime enum read is STRICT since R2-11 Phase C, so a
+    ///     typo rejects the tag), or an out-of-range <c>stringLength</c> on a <c>String</c> tag. Such a tag
+    ///     is skipped by the driver and reads <c>BadNodeIdUnknown</c> forever. Empty when the mapper accepts
+    ///     the blob, when it is blank, or when it is not an equipment-tag object. Never throws.
+    /// </summary>
+    /// <remarks>
+    ///     <b>The verdict comes from <see cref="FromTagConfig"/>, not from a mirror</b> (Gitea #551) — see
+    ///     <c>ModbusTagDefinitionFactory.Inspect</c>'s remarks for the full argument.
+    /// </remarks>
    /// <param name="reference">The equipment tag's TagConfig JSON.</param>
    /// <returns>The warnings; empty when clean.</returns>
    public static IReadOnlyList<string> Inspect(string reference)
    {
        var warnings = new List<string>();
        if (string.IsNullOrWhiteSpace(reference) || reference[0] != '{') return warnings;
+
+        // The accept gate: whatever the driver reads draws nothing.
+        if (FromTagConfig(reference, InspectionRawPath, out _)) return warnings;
+
        try
        {
            using var doc = JsonDocument.Parse(reference);
@@ -130,16 +175,67 @@ public static class S7TagDefinitionFactory
                warnings.Add("S7 TagConfig root is not a JSON object — the tag will not resolve (BadNodeIdUnknown).");
                return warnings;
            }
-            var w = TagConfigJson.DescribeInvalidEnum<S7DataType>(root, "dataType");
-            if (w is not null) warnings.Add(w);
+
+            DescribeRejection(root, warnings);
        }
        catch (JsonException)
        {
            warnings.Add("S7 TagConfig is not valid JSON — the tag will not resolve (BadNodeIdUnknown).");
+            return warnings;
        }
+
+        if (warnings.Count == 0)
+        {
+            warnings.Add(
+                "S7 TagConfig was rejected by the driver's tag reader — the driver will skip this tag and "
+                + "it will read BadNodeIdUnknown.");
+        }
+
        return warnings;
    }

+    /// <summary>
+    ///     Explains why <see cref="FromTagConfig"/> refused an object-rooted blob, walking its checks in the
+    ///     same order. Runs only after the mapper has already refused, so it can never invent strictness.
+    /// </summary>
+    /// <param name="root">The TagConfig root object.</param>
+    /// <param name="warnings">The list to append warnings to.</param>
+    private static void DescribeRejection(JsonElement root, List<string> warnings)
+    {
+        if (!root.TryGetProperty("address", out var addrEl) || addrEl.ValueKind != JsonValueKind.String)
+        {
+            warnings.Add(
+                "S7 TagConfig has no string 'address' (e.g. DB1.DBW0, M0.0, I0.0, QD4) — the driver will "
+                + "skip this tag and it will read BadNodeIdUnknown.");
+        }
+        else if (string.IsNullOrWhiteSpace(addrEl.GetString()))
+        {
+            warnings.Add("S7 TagConfig has a blank 'address' — the tag will not resolve (BadNodeIdUnknown).");
+        }
+
+        if (!DeclaresDataType(root))
+        {
+            warnings.Add(
+                "S7 TagConfig has no 'dataType' — the S7 reader REQUIRES the key to be present (unlike its "
+                + "sibling drivers, which default it), so the driver will skip this tag and it will read "
+                + "BadNodeIdUnknown. Valid: " + string.Join(", ", Enum.GetNames<S7DataType>()) + ".");
+        }
+
+        if (TagConfigJson.DescribeInvalidEnum<S7DataType>(root, DataTypeKey) is { } w) warnings.Add(w);
+
+        if (TagConfigJson.TryReadEnumStrict(root, DataTypeKey, S7DataType.Int16, out var dataType)
+            && dataType == S7DataType.String)
+        {
+            var stringLength = ReadInt(root, "stringLength");
+            if (stringLength < 0 || stringLength > MaxStringLength)
+            {
+                warnings.Add(
+                    $"S7 String tag has a 'stringLength' of {stringLength} — an S7 string is 0–"
+                    + $"{MaxStringLength} characters, so the tag is rejected (BadNodeIdUnknown).");
+            }
+        }
+    }
+
    private static int ReadInt(JsonElement o, string name)
        => o.TryGetProperty(name, out var e) && e.ValueKind == JsonValueKind.Number
           && e.TryGetInt32(out var v) ? v : 0;
@@ -109,16 +109,34 @@ public static class TwinCATTagDefinitionFactory
    }

    /// <summary>
-    ///     Deploy-time inspection (05/CONV-2): warns on a present-but-invalid <c>dataType</c> (silently
-    ///     defaulted by the lenient runtime) and on a structurally unparseable TagConfig. Empty when clean
-    ///     or not an equipment-tag object. Never throws.
+    ///     The RawPath handed to <see cref="FromTagConfig"/> during inspection — the mapper only copies it
+    ///     onto <see cref="TwinCATTagDefinition.Name"/> and never validates it.
    /// </summary>
+    private const string InspectionRawPath = "(inspect)";
+
+    /// <summary>
+    ///     Deploy-time inspection (05/CONV-2): warns for a blob <see cref="FromTagConfig"/> would
+    ///     <b>reject</b> — a structurally unparseable or non-object document, an absent / non-string /
+    ///     blank <c>symbolPath</c>, a present-but-invalid <c>dataType</c> (the runtime enum read is STRICT
+    ///     since R2-11 Phase C, so a typo rejects the tag), or the unsupported
+    ///     <see cref="TwinCATDataType.Structure"/> type. Such a tag is skipped by the driver and reads
+    ///     <c>BadNodeIdUnknown</c> forever. Empty when the mapper accepts the blob, when it is blank, or
+    ///     when it is not an equipment-tag object. Never throws.
+    /// </summary>
+    /// <remarks>
+    ///     <b>The verdict comes from <see cref="FromTagConfig"/>, not from a mirror</b> (Gitea #551) — see
+    ///     <c>ModbusTagDefinitionFactory.Inspect</c>'s remarks for the full argument.
+    /// </remarks>
    /// <param name="reference">The equipment tag's TagConfig JSON.</param>
    /// <returns>The warnings; empty when clean.</returns>
    public static IReadOnlyList<string> Inspect(string reference)
    {
        var warnings = new List<string>();
        if (string.IsNullOrWhiteSpace(reference) || reference[0] != '{') return warnings;
+
+        // The accept gate: whatever the driver reads draws nothing.
+        if (FromTagConfig(reference, InspectionRawPath, out _)) return warnings;
+
        try
        {
            using var doc = JsonDocument.Parse(reference);
@@ -128,16 +146,56 @@ public static class TwinCATTagDefinitionFactory
                warnings.Add("TwinCAT TagConfig root is not a JSON object — the tag will not resolve (BadNodeIdUnknown).");
                return warnings;
            }
-            var w = TagConfigJson.DescribeInvalidEnum<TwinCATDataType>(root, "dataType");
-            if (w is not null) warnings.Add(w);
+
+            DescribeRejection(root, warnings);
        }
        catch (JsonException)
        {
            warnings.Add("TwinCAT TagConfig is not valid JSON — the tag will not resolve (BadNodeIdUnknown).");
+            return warnings;
        }
+
+        if (warnings.Count == 0)
+        {
+            warnings.Add(
+                "TwinCAT TagConfig was rejected by the driver's tag reader — the driver will skip this tag "
+                + "and it will read BadNodeIdUnknown.");
+        }
+
        return warnings;
    }

+    /// <summary>
+    ///     Explains why <see cref="FromTagConfig"/> refused an object-rooted blob, walking its checks in the
+    ///     same order. Runs only after the mapper has already refused, so it can never invent strictness.
+    /// </summary>
+    /// <param name="root">The TagConfig root object.</param>
+    /// <param name="warnings">The list to append warnings to.</param>
+    private static void DescribeRejection(JsonElement root, List<string> warnings)
+    {
+        if (!root.TryGetProperty("symbolPath", out var symbol) || symbol.ValueKind != JsonValueKind.String)
+        {
+            warnings.Add(
+                "TwinCAT TagConfig has no string 'symbolPath' (e.g. MAIN.bStart) — the driver will skip "
+                + "this tag and it will read BadNodeIdUnknown.");
+        }
+        else if (string.IsNullOrWhiteSpace(symbol.GetString()))
+        {
+            warnings.Add("TwinCAT TagConfig has a blank 'symbolPath' — the tag will not resolve (BadNodeIdUnknown).");
+        }
+
+        if (TagConfigJson.DescribeInvalidEnum<TwinCATDataType>(root, "dataType") is { } w) warnings.Add(w);
+
+        if (TagConfigJson.TryReadEnumStrict(root, "dataType", TwinCATDataType.DInt, out var dataType)
+            && dataType == TwinCATDataType.Structure)
+        {
+            warnings.Add(
+                "TwinCAT 'dataType' is Structure — the driver does not support UDT / FB-instance tags and "
+                + "rejects them (BadNodeIdUnknown). Declare the atomic-typed members instead, or use "
+                + "EnableControllerBrowse to discover them individually.");
+        }
+    }
+
    /// <summary>
    ///     Reads the optional 1-D array length: <c>arrayLength</c> (a positive int32; values above
    ///     <see cref="int.MaxValue"/> are treated as absent/scalar) honoured ONLY when <c>isArray</c>
@@ -19,6 +19,14 @@ namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns;
 /// columns. A typed column therefore <b>wins</b> over a conflicting key carried in the <c>TagConfigJson</c>
 /// fallback; the review model flags when that override happened so the operator sees it.
 /// </para>
+/// <para>
+/// The assembled blob is then put to the driver's own <see cref="TagConfigValidator"/> (Gitea #551): the
+/// typed columns were always strictly parsed, but the free-form <c>TagConfigJson</c> column reached the
+/// database unread, so a CSV could author a tag the driver rejects — one that deploys clean and reads
+/// <c>BadNodeIdUnknown</c> forever. A failing row is an <b>error</b>, blocking the all-or-nothing commit;
+/// it is never silently skipped. This check is for the operator's benefit (it names the row before
+/// commit); the guarantee lives in <see cref="IRawTreeService.ImportTagsAsync"/>, which re-runs it.
+/// </para>
 /// </summary>
 public static class RawTagCsvMapper
 {
@@ -84,7 +92,7 @@ public static class RawTagCsvMapper
                continue;
            }

-            reviewed.Add(BuildRow(r, headers, headerIndex, cells, map, groupPathPrefix));
+            reviewed.Add(BuildRow(r, headers, headerIndex, cells, driverType, map, groupPathPrefix));
        }

        FlagDuplicates(reviewed);
@@ -96,6 +104,7 @@ public static class RawTagCsvMapper
        string[] headers,
        IReadOnlyDictionary<string, int> headerIndex,
        string[] cells,
+        string driverType,
        CsvDriverTagMap? map,
        string? groupPathPrefix)
    {
@@ -193,6 +202,19 @@ public static class RawTagCsvMapper
            // Alarm flags — an alarm is authored iff Alarm.AlarmType is present.
            json = ApplyAlarm(json, Cell("Alarm.AlarmType"), Cell("Alarm.Severity"), Cell("Alarm.HistorizeToAveva"));

+            // The driver-typed config gate, on the FINAL assembled blob (Gitea #551 item 1). Until this,
+            // the typed columns above were strictly parsed but the free-form TagConfigJson column was not
+            // checked at all, so a CSV could import a blob the driver rejects — a tag that deploys clean
+            // and then reads BadNodeIdUnknown forever. Surfacing it here, on the staged review row, is what
+            // lets the operator SEE which row is wrong before committing; IRawTreeService.ImportTagsAsync
+            // re-checks it as the actual guarantee (a form/grid cannot cover the API or a future caller).
+            // A rejected row is an ERROR, never a skip: the commit is all-or-nothing, and "skipped" would
+            // claim the tag is already present.
+            if (TagConfigValidator.Validate(driverType, json) is { } configError)
+            {
+                return Invalid(rowNumber, cells, $"TagConfig: {configError}");
+            }
+
            var importRow = new RawTagImportRow(groupPath, new RawTagInput(name, dataType, access, writeIdempotent, pollGroupId, json));

            return new RawCsvReviewRow
@@ -1,5 +1,6 @@
 using System.Text.Json;
 using Microsoft.EntityFrameworkCore;
+using ZB.MOM.WW.OtOpcUa.AdminUI.Uns.TagEditors;
 using ZB.MOM.WW.OtOpcUa.Commons.Types;
 using ZB.MOM.WW.OtOpcUa.Configuration;
 using ZB.MOM.WW.OtOpcUa.Configuration.Entities;
@@ -834,6 +835,9 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
                t => t.DeviceId == deviceId && t.TagGroupId == tagGroupId && t.Name == input.Name, ct))
            return new UnsMutationResult(false, $"A tag named '{input.Name}' already exists here.");

+        if (await ValidateTagConfigAsync(db, deviceId, tagConfig, ct) is { } configError)
+            return new UnsMutationResult(false, configError);
+
        var id = NewId("TAG");
        db.Tags.Add(new Tag
        {
@@ -872,6 +876,9 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
                     && t.Name == input.Name && t.TagId != tagId, ct))
            return new UnsMutationResult(false, $"A tag named '{input.Name}' already exists here.");

+        if (await ValidateTagConfigAsync(db, entity.DeviceId, tagConfig, ct) is { } configError)
+            return new UnsMutationResult(false, configError);
+
        db.Entry(entity).Property(e => e.RowVersion).OriginalValue = rowVersion;
        entity.Name = input.Name;
        entity.DataType = input.DataType;
@@ -902,6 +909,10 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
        if (!await db.Devices.AnyAsync(dev => dev.DeviceId == deviceId, ct))
            return new RawTagImportResult(0, new[] { $"Device '{deviceId}' not found." });

+        // The device's driver type, resolved ONCE: an import is per-device, and a device hangs off exactly
+        // one driver, so every row in the batch is judged by the same driver's rules (Gitea #551 item 1).
+        var driverType = await ResolveDriverTypeAsync(db, deviceId, ct);
+
        // Existing groups on the device: a (parent-group-id | null, name) → group-id lookup we extend with
        // pending (auto-created) groups so a repeated path within the batch resolves to one group.
        var groupLookup = (await db.TagGroups.AsNoTracking()
@@ -951,6 +962,15 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
                continue;
            }

+            // The driver-typed config gate. A rejected row is an ERROR — the import is all-or-nothing, so
+            // the batch inserts nothing and the row is NAMED; it is never skipped ("skipped" would claim
+            // the tag is already present). See ValidateTagConfigAsync for why this lives in the service.
+            if (TagConfigValidator.Validate(driverType, tagConfig) is { } configError)
+            {
+                errors.Add($"{rowLabel}: TagConfig: {configError}");
+                continue;
+            }
+
            if (!takenNames.Add((groupId, row.Tag.Name)))
            {
                errors.Add($"{rowLabel}: a tag named '{row.Tag.Name}' already exists at that path.");
@@ -1196,6 +1216,55 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
        }
    }

+    /// <summary>
+    ///     The driver-type string of the driver a device hangs off, or <see langword="null"/> when the
+    ///     device (or its driver) is gone. Joined in exactly as <c>LoadDeviceForEditAsync</c> does — a
+    ///     device carries no driver type of its own.
+    /// </summary>
+    /// <param name="db">The open context.</param>
+    /// <param name="deviceId">The device whose driver type to resolve.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>The canonical driver-type string, or null.</returns>
+    private static Task<string?> ResolveDriverTypeAsync(
+        OtOpcUaConfigDbContext db, string deviceId, CancellationToken ct)
+        => db.Devices.AsNoTracking()
+            .Where(dev => dev.DeviceId == deviceId)
+            .Join(db.DriverInstances.AsNoTracking(),
+                dev => dev.DriverInstanceId,
+                drv => drv.DriverInstanceId,
+                (dev, drv) => drv.DriverType)
+            .FirstOrDefaultAsync(ct);
+
+    /// <summary>
+    ///     The driver-typed <c>TagConfig</c> gate, applied on the SERVER for every tag-writing path —
+    ///     create, update and bulk import alike (Gitea #551 item 1).
+    ///     <para>
+    ///         <b>It lives here rather than in the modals because a form cannot be the guarantee.</b> The
+    ///         tag modal and the manual-entry grid already run <see cref="TagConfigValidator"/> for fast
+    ///         feedback, but the CSV import did not, and the API and any future caller reach none of them —
+    ///         so a blob the driver rejects could be persisted, deploy clean, and read
+    ///         <c>BadNodeIdUnknown</c> forever. This repo also has no bUnit, so a rule only a page enforces
+    ///         is a rule no test can reach.
+    ///     </para>
+    ///     <para>
+    ///         The rule itself is not stated here: <see cref="TagConfigValidator"/> dispatches to the
+    ///         driver's typed model, which in turn asks the driver's own reader. An unmapped driver type
+    ///         (Galaxy) validates to null, exactly as it does in the modals.
+    ///     </para>
+    /// </summary>
+    /// <param name="db">The open context.</param>
+    /// <param name="deviceId">The device the tag belongs to (supplies the driver type).</param>
+    /// <param name="tagConfig">The normalised TagConfig JSON about to be persisted.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>An operator-facing error, or <see langword="null"/> when the config is acceptable.</returns>
+    private static async Task<string?> ValidateTagConfigAsync(
+        OtOpcUaConfigDbContext db, string deviceId, string tagConfig, CancellationToken ct)
+    {
+        var driverType = await ResolveDriverTypeAsync(db, deviceId, ct);
+        var error = TagConfigValidator.Validate(driverType, tagConfig);
+        return error is null ? null : $"TagConfig: {error}";
+    }
+
    /// <summary>Ordinal (case-sensitive) equality for a nullable-parent + name tag-group key.</summary>
    private sealed class GroupKeyComparer : IEqualityComparer<(string? Parent, string Name)>
    {
@@ -59,11 +59,23 @@ public sealed class AbCipTagConfigModel
    ///     (<c>BadNodeIdUnknown</c>). Without this the blob would be accepted here, silently rewritten to
    ///     <c>DInt</c> on save, and — on the CSV-import and API paths, which save it verbatim — deployed
    ///     into a tag the driver skips (Gitea #549).
+    ///     <para>
+    ///         <b>Declared UDT members are checked too (Gitea #551), and the rule is not restated here.</b>
+    ///         The member rules are as strict as the top-level ones — one member with no <c>name</c> or a
+    ///         typo'd <c>dataType</c> rejects the WHOLE tag — but nothing on the authoring side saw them:
+    ///         this editor emits only <c>tagPath</c>/<c>dataType</c>/<c>writable</c>, so <c>members</c>
+    ///         rides <see cref="_bag"/> untouched from whatever hand-authored / CSV / API blob produced it.
+    ///         The verdict AND the wording come from
+    ///         <see cref="AbCipTagDefinitionFactory.DescribeInvalidMember(string)"/>, the same authority the
+    ///         driver's reader and the deploy gate consult, so this gate cannot drift from the runtime in
+    ///         either direction.
+    ///     </para>
    /// </remarks>
    /// <returns>An error message describing the validation failure, or <c>null</c> when valid.</returns>
    public string? Validate()
    {
        if (TagConfigJson.DescribeInvalidEnum<AbCipDataType>(_bag, "dataType") is { } dtError) { return dtError; }
-        return string.IsNullOrWhiteSpace(TagPath) ? "Tag path is required." : null;
+        if (string.IsNullOrWhiteSpace(TagPath)) { return "Tag path is required."; }
+        return AbCipTagDefinitionFactory.DescribeInvalidMember(TagConfigJson.Serialize(_bag));
    }
 }
@@ -69,17 +69,26 @@ public sealed class ModbusTagConfigModel

    /// <summary>Validation hook; returns an error message or null when the model is valid.</summary>
    /// <remarks>
-    ///     All three enums are read from the ORIGINAL key bag, not from the leniently-defaulted typed
+    ///     All FOUR enums are read from the ORIGINAL key bag, not from the leniently-defaulted typed
    ///     fields above: <c>ModbusTagDefinitionFactory</c> reads each with <c>TryReadEnumStrict</c>, so a
    ///     present-but-invalid string rejects the whole tag at the driver (<c>BadNodeIdUnknown</c>) where
-    ///     the load silently substitutes <c>HoldingRegisters</c>/<c>Int16</c>/<c>BigEndian</c>. Accepting
-    ///     one here would let the CSV-import and API paths — which save the blob verbatim — deploy a tag
-    ///     the driver skips (Gitea #549). Also note a <b>wrong-but-valid</b> region is not this gate's
-    ///     business: only a spelling the runtime cannot read is rejected.
+    ///     the load silently substitutes <c>HoldingRegisters</c>/<c>Int16</c>/<c>BigEndian</c>/
+    ///     <c>HighByteFirst</c>. Accepting one here would let the CSV-import and API paths — which save the
+    ///     blob verbatim — deploy a tag the driver skips (Gitea #549). Also note a <b>wrong-but-valid</b>
+    ///     region is not this gate's business: only a spelling the runtime cannot read is rejected.
+    ///     <para>
+    ///         <c>stringByteOrder</c> is the fourth (Gitea #551): the runtime has always read it as
+    ///         strictly as its three siblings, but this model — and the deploy gate's <c>Inspect</c> —
+    ///         checked only the other three, so a typo'd <c>stringByteOrder</c> passed BOTH gates and died
+    ///         at the driver. It is not in <see cref="ToJson"/>'s exposed-field list either, so it can only
+    ///         ever reach the bag from a hand-authored blob, a CSV import or the API — exactly the paths
+    ///         this gate exists for.
+    ///     </para>
    /// </remarks>
    /// <returns>An error message describing the validation failure, or <c>null</c> when the model is valid.</returns>
    public string? Validate()
        => TagConfigJson.DescribeInvalidEnum<ModbusRegion>(_bag, "region")
            ?? TagConfigJson.DescribeInvalidEnum<ModbusDataType>(_bag, "dataType")
-            ?? TagConfigJson.DescribeInvalidEnum<ModbusByteOrder>(_bag, "byteOrder");
+            ?? TagConfigJson.DescribeInvalidEnum<ModbusByteOrder>(_bag, "byteOrder")
+            ?? TagConfigJson.DescribeInvalidEnum<ModbusStringByteOrder>(_bag, "stringByteOrder");
 }
@@ -22,6 +22,19 @@ public sealed class S7TagConfigModel

    private JsonObject _bag = new();

+    // Whether the blob this model was LOADED FROM was missing the "dataType" key entirely — captured
+    // because the lenient load above cannot tell "absent" from "present": both land on Int16. S7 is the one
+    // driver whose reader REQUIRES the key (S7TagDefinitionFactory.DeclaresDataType), so a blob without one
+    // is rejected outright and reads BadNodeIdUnknown; without this capture that blob validated clean
+    // (Gitea #551). Same capture-the-as-loaded-shape pattern as MTConnectTagConfigModel's _rawDataType.
+    //
+    // It records a property of the SOURCE, so the default (false) is the honest answer for a model built by
+    // object initialiser rather than loaded — RawBrowseCommitMapper does exactly that, and ToJson() then
+    // writes the key from the typed DataType field. ToJson() likewise clears it: a blob that has been
+    // re-serialised through this model always carries the key, so it can only ever be true on the FIRST
+    // load of a blob authored elsewhere (hand-edited, CSV import, API).
+    private bool _dataTypeMissingInSource;
+
    /// <summary>Loads a model from a TagConfig JSON string, defaulting any absent field and retaining
    /// every original key (so fields this editor doesn't expose survive a load→save).</summary>
    /// <param name="json">The raw TagConfig JSON string, or null/empty for a fresh model.</param>
@@ -32,9 +45,10 @@ public sealed class S7TagConfigModel
        return new S7TagConfigModel
        {
            Address = TagConfigJson.GetString(o, "address") ?? "",
-            DataType = TagConfigJson.GetEnum(o, "dataType", S7DataType.Int16),
+            DataType = TagConfigJson.GetEnum(o, S7TagDefinitionFactory.DataTypeKey, S7DataType.Int16),
            StringLength = TagConfigJson.GetInt(o, "stringLength"),
            Writable = TagConfigJson.GetBoolNullable(o, "writable"),
+            _dataTypeMissingInSource = !o.ContainsKey(S7TagDefinitionFactory.DataTypeKey),
            _bag = o,
        };
    }
@@ -45,7 +59,8 @@ public sealed class S7TagConfigModel
    public string ToJson()
    {
        TagConfigJson.Set(_bag, "address", Address.Trim());
-        TagConfigJson.Set(_bag, "dataType", DataType);
+        TagConfigJson.Set(_bag, S7TagDefinitionFactory.DataTypeKey, DataType);
+        _dataTypeMissingInSource = false;
        TagConfigJson.Set(_bag, "stringLength", StringLength);
        TagConfigJson.Set(_bag, "writable", Writable);
        return TagConfigJson.Serialize(_bag);
@@ -59,10 +74,36 @@ public sealed class S7TagConfigModel
    ///     so a present-but-invalid string rejects the whole tag at the driver (<c>BadNodeIdUnknown</c>)
    ///     where the load silently substitutes <c>Int16</c>. Accepting it here would let the CSV-import
    ///     and API paths — which save the blob verbatim — deploy an unreadable tag (Gitea #549).
+    ///     <para>
+    ///         <b>An ABSENT <c>dataType</c> is rejected too (Gitea #551), and S7 is the only driver where
+    ///         that is right.</b> <c>S7TagDefinitionFactory.FromTagConfig</c> refuses a blob that does not
+    ///         carry the key at all — unique in the fleet, where every sibling falls back to a default — so
+    ///         such a tag deployed clean through both gates and then read <c>BadNodeIdUnknown</c> forever.
+    ///         Presence is judged on the key, not the value, matching
+    ///         <see cref="S7TagDefinitionFactory.DeclaresDataType"/>: a non-string token is present-enough
+    ///         for the reader, which then treats it as absent and accepts the tag as <c>Int16</c>.
+    ///     </para>
+    ///     <para>
+    ///         <b>The one blob this can newly block in the modal is one that was already dead.</b> The
+    ///         typed editor pushes <see cref="ToJson"/> — which always writes <c>dataType</c> — only when a
+    ///         field CHANGES, so opening a legacy key-less blob and saving it untouched hands this method
+    ///         the as-loaded string. That save is refused, and correctly: the tag it would persist is one
+    ///         the driver already skips. Picking any data type in the editor writes the key and clears it.
+    ///     </para>
    /// </remarks>
    public string? Validate()
    {
-        if (TagConfigJson.DescribeInvalidEnum<S7DataType>(_bag, "dataType") is { } dtError) { return dtError; }
-        return string.IsNullOrWhiteSpace(Address) ? "Address is required." : null;
+        if (TagConfigJson.DescribeInvalidEnum<S7DataType>(_bag, S7TagDefinitionFactory.DataTypeKey) is { } dtError)
+        {
+            return dtError;
+        }
+
+        if (string.IsNullOrWhiteSpace(Address)) { return "Address is required."; }
+
+        return _dataTypeMissingInSource
+            ? "A data type is required — the S7 driver rejects a tag whose TagConfig carries no "
+              + $"'{S7TagDefinitionFactory.DataTypeKey}' key (it would read BadNodeIdUnknown). Valid: "
+              + string.Join(", ", Enum.GetNames<S7DataType>()) + "."
+            : null;
    }
 }
@@ -246,8 +246,11 @@ public sealed class AdminOperationsActor : ReceiveActor
            }

            // R2-11 (05/CONV-2): deploy-time TagConfig strictness inspection over equipment tags. The
-            // driver-typed EquipmentTagConfigInspector surfaces present-but-invalid enum values (which the
-            // lenient runtime silently defaults) + structurally-unparseable TagConfig. In Warn mode
+            // driver-typed EquipmentTagConfigInspector surfaces every blob the driver's own reader would
+            // REJECT — a present-but-invalid enum value, an absent or malformed address field, a
+            // structurally-unparseable TagConfig — each of which makes the driver skip the tag so it reads
+            // BadNodeIdUnknown forever. (Pre-R2-11 Phase C the runtime silently defaulted a typo'd enum;
+            // it has rejected the tag since, so these warnings describe rejections.) In Warn mode
            // (default) these are non-blocking (logged + appended to the accepted result Message); in Error
            // mode they fold into the reject list so a typo'd config cannot be re-deployed until fixed.
            // Running servers are untouched either way — the gate only sees re-deploys.
@@ -17,8 +17,17 @@ namespace ZB.MOM.WW.OtOpcUa.ControlPlane.AdminOperations;
 ///     Deploy-time TagConfig inspection dispatched by <c>DriverType</c> (R2-11, 05/CONV-2). Mirrors the
 ///     AdminUI <c>TagConfigValidator</c> shape: a case-insensitive map from the canonical driver-type string
 ///     to that driver's lightweight <c>Contracts</c> parser <c>Inspect()</c>, returning human-readable
-///     warnings (present-but-invalid enum values that the lenient runtime silently defaults, plus
-///     structurally-unparseable TagConfig). Never throws.
+///     warnings. Never throws.
+///     <para><b>The warnings describe REJECTIONS, not silent defaults.</b> Every driver's runtime read has
+///     been strict since R2-11 Phase C (<c>TagConfigJson.TryReadEnumStrict</c>): a present-but-invalid enum
+///     value — like an absent or malformed address field, or an unparseable document — makes the reader
+///     refuse the whole tag, so the driver skips it and it reads <c>BadNodeIdUnknown</c> forever with the
+///     deployment otherwise green. That is what these warnings are for. (Before Phase C the runtime did
+///     silently substitute a default for a typo'd enum; the doc-comments here and on the per-driver
+///     <c>Inspect</c> methods still said so until Gitea #551.) Because a warning can be PROMOTED to a
+///     blocking error by <c>TagConfigValidationMode.Error</c>, each <c>Inspect</c> asks its driver's own
+///     reader for the verdict and only explains a refusal — never restating the rule, and so never able to
+///     be stricter than the runtime it reports on.</para>
 ///     <para><b>Coverage is every driver that ships an <c>Inspect</c>, and that invariant is guarded</b> by
 ///     <c>EquipmentTagConfigInspectorCoverageTests</c>, which reflects over the referenced
 ///     <c>*.Contracts</c> assemblies — so a driver that gains an inspector cannot be silently left out. This