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>