docs(mtconnect): describe the fixed browse-commit coercion type (#560)

The comments and docs that described Driver.MTConnect-003 as live at HEAD would
have been wrong the moment 64be41d8 landed:

- code-reviews/Driver.MTConnect/findings.md — Driver.MTConnect-003 Resolved,
  with the fixing commit; module open-finding count 5 -> 4.
- code-reviews/Driver.MTConnect.Contracts/findings.md — the one clause inside
  Contracts-001's prose that asserted 003 was Open.
- docs/drivers/MTConnect.md — the coercion-precedence warning now states that a
  browse-committed tag resolves at step 1 CARRYING the step-3 answer, and that
  step 3 remains the rescue for a hand-authored / CSV / API blob with no type.
- MTConnectDriver.BuildBinding, MTConnectDataTypeInference and
  MTConnectDriverOptions.RawTags remarks — same correction, each keeping a short
  historical note of what the defect was so a reader meeting the old blobs still
  understands them.

Comment-only in src; the driver suite (538) and AdminUI suite (1474) re-run green.
This commit is contained in:
Joseph Doherty
2026-08-10 07:36:45 -04:00
parent 64be41d80c
commit 1c67d019e5
6 changed files with 57 additions and 38 deletions
@@ -37,13 +37,15 @@ public readonly record struct MTConnectInferredType(DriverDataType DataType, boo
/// blob declares no type).
/// </para>
/// <para>
/// ⚠️ <b>Two call sites this remark used to name do not exist.</b> The universal browser's
/// commit path (<c>RawBrowseCommitMapper</c>) never calls this — it re-maps the browsed leaf's
/// already-inferred <c>DriverDataType</c> onto the raw tag's OPC UA type but writes a
/// <c>TagConfig</c> whose <c>dataType</c> is the model default — and the AdminUI typed editor
/// (<c>MTConnectTagConfigModel</c>) deliberately does not recompute the inference at all. The
/// first of those is a live defect, not merely a stale comment: see
/// <c>code-reviews/Driver.MTConnect/findings.md</c> (Driver.MTConnect-003).
/// <b>Two further call sites this remark used to name do not exist, and should not.</b> The
/// universal browser's commit path (<c>RawBrowseCommitMapper</c>) never calls this: it
/// FORWARDS the browsed leaf's already-inferred <c>DriverDataType</c> — onto the raw tag's OPC
/// UA type, and (since Gitea #560) into the committed <c>TagConfig</c>'s <c>dataType</c> — so
/// both come from this rule without re-running it. Before #560 the blob carried the model's
/// <c>String</c> default instead and disagreed with the node beside it
/// (<c>Driver.MTConnect-003</c>). The AdminUI typed editor (<c>MTConnectTagConfigModel</c>)
/// deliberately does not recompute the inference at all — it re-serialises whatever the
/// operator picked or the commit stamped.
/// </para>
/// <para>
/// <b>MTConnect is weakly typed on the wire</b> — every observation is text, and the standard
@@ -87,10 +87,13 @@ public sealed class MTConnectDriverOptions
/// <see cref="Tags"/> entry naming the same DataItem id; failing that, from the Agent's
/// own <c>/probe</c> declaration (<see cref="MTConnectDataTypeInference"/>); failing
/// that, <see cref="DriverDataType.String"/> — the coercion that cannot fail.
/// ⚠️ The <c>/probe</c> step is <b>not</b> reached by a browse-committed tag at HEAD:
/// the AdminUI's commit mapper writes a full typed blob whose <c>dataType</c> defaults
/// to <c>String</c>, which the first step then honours. See
/// <c>code-reviews/Driver.MTConnect/findings.md</c> (Driver.MTConnect-003).</item>
/// The <c>/probe</c> step is not reached by a browse-committed tag — the AdminUI's
/// commit mapper writes a full typed blob, so the first step always answers — but
/// since Gitea #560 the type it writes IS the browsed leaf's inference, so the answer
/// is the same one. It previously wrote the model's <c>String</c> default and silently
/// mistyped every browsed tag (<c>code-reviews/Driver.MTConnect/findings.md</c>,
/// Driver.MTConnect-003). The step still serves a hand-authored / CSV / API blob that
/// states no type.</item>
/// <item>A tag in <see cref="Tags"/> only is reachable by its DataItem <c>id</c>
/// (the driver CLI's authoring surface, and every pre-v3 test) and still contributes
/// its coercion type to the index.</item>
@@ -3227,19 +3227,18 @@ public sealed class MTConnectDriver
/// data item, else <see cref="DriverDataType.String"/>.
/// </para>
/// <para>
/// ⚠️ <b>The third step does NOT currently rescue a browse-committed tag, and the
/// AdminUI is where that has to be fixed.</b> It was written on the premise that
/// <c>RawBrowseCommitMapper</c> writes only the address into the blob — true when this
/// was authored, false at HEAD: the MTConnect branch of
/// <c>RawBrowseCommitMapper.BuildTagConfig</c> now emits a whole
/// <b>A browse-committed tag never reaches the third step, and no longer needs to.</b>
/// The MTConnect branch of <c>RawBrowseCommitMapper.BuildTagConfig</c> emits a whole
/// <c>MTConnectTagConfigModel</c>, whose <c>ToJson</c> unconditionally writes
/// <c>"dataType"</c> from a field defaulting to <see cref="DriverDataType.String"/>. That
/// is a non-blank authored type, so step 1 wins and this step is never reached — every
/// browse-committed tag coerces to text while its raw-tag node was typed <c>Double</c> /
/// <c>Int64</c> from the SAME probe inference (<c>RawBrowseCommitMapper.MapLeaf</c>).
/// The step is kept because it is still the correct rule and still serves a blob authored
/// by hand, by CSV or by API with no type; see
/// <c>code-reviews/Driver.MTConnect/findings.md</c> (Driver.MTConnect-003).
/// <c>"dataType"</c> — always a non-blank authored type, so step 1 always wins. Since
/// Gitea #560 the value it writes is the browsed leaf's own inferred
/// <see cref="DriverDataType"/>, i.e. what this step would have computed, so it agrees
/// with the raw-tag node's OPC UA type (taken from the same inference by
/// <c>RawBrowseCommitMapper.MapLeaf</c>). Historically it wrote the model's
/// <see cref="DriverDataType.String"/> default instead, and every browse-committed tag
/// coerced to text inside a <c>Double</c>/<c>Int64</c> node — <c>Driver.MTConnect-003</c>.
/// The step remains the rescue for a blob authored by hand, by CSV or by API that states
/// no type at all.
/// </para>
/// </remarks>
/// <param name="options">The options document to derive from.</param>