docs: fill missing XML docs and strip tracking IDs from src comments

Clears CommentChecker findings in src/ (3,280 -> 209, the remainder being false
positives like PLC-5/IEEE-754/M0.0) by adding missing summaries/params/returns,
normalising inheritdoc usage, and removing Gitea/review tracking IDs while keeping
the rationale they annotated. Comment-only: comment-stripped sources are identical
to the parent commit.
This commit is contained in:
Joseph Doherty
2026-10-15 06:14:58 -04:00
parent ebcbd81fca
commit 826312befe
430 changed files with 4434 additions and 3923 deletions
@@ -4,7 +4,7 @@ using ZB.MOM.WW.OtOpcUa.Configuration.Enums;
namespace ZB.MOM.WW.OtOpcUa.AdminUI.Acls;
/// <summary>
/// One row in the ACL scope picker (#520 stage 7) — a place a <c>NodeAcl</c> grant can be scoped at,
/// One row in the ACL scope picker — a place a <c>NodeAcl</c> grant can be scoped at,
/// in either the raw device tree or the UNS tree.
/// </summary>
/// <remarks>
@@ -3,7 +3,7 @@ using ZB.MOM.WW.OtOpcUa.Configuration.Enums;
namespace ZB.MOM.WW.OtOpcUa.AdminUI.Acls;
/// <summary>
/// Backs the ACL authoring surface (#520 stage 7): the scope picker's two trees, and the
/// Backs the ACL authoring surface: the scope picker's two trees, and the
/// authoring-time checks that stop a grant being saved against a principal or a scope that names
/// nothing.
/// </summary>
@@ -3,7 +3,7 @@ using ZB.MOM.WW.OtOpcUa.Commons.Browsing;
namespace ZB.MOM.WW.OtOpcUa.AdminUI.Browsing;
/// <summary>
/// Payload for a leaf toggle in <c>DriverBrowseTree</c>'s multi-select mode (WP6 "Browse device…"
/// Payload for a leaf toggle in <c>DriverBrowseTree</c>'s multi-select mode ("Browse device…"
/// re-target). Carries the toggled <see cref="Leaf"/> plus the captured browse-folder nesting above it
/// (<see cref="FolderPath"/>, root→parent display names) so the browse modal can optionally mirror the
/// nesting onto TagGroups on commit. Fired only for <see cref="BrowseNodeKind.Leaf"/> nodes.
@@ -87,21 +87,15 @@ public sealed class BrowserSessionService(
InvokeAsync<IReadOnlyList<AttributeInfo>>(token, ct, (s, c) => s.AttributesAsync(nodeId, c));
/// <inheritdoc />
/// <remarks>
/// <para>
/// <b>The authorization check is the point of routing this through the service at all.</b>
/// Every other member here is read-only; this one causes the browse session to publish onto
/// a live plant broker, so it is gated on the same <c>DriverOperator</c> policy the picker
/// bodies evaluate before rendering their Browse affordance. A render-time check alone is
/// not a control — it decides what a page draws, not what a circuit may invoke — so the
/// check is made here, where the action actually happens, and it fails closed.
/// </para>
/// <para>
/// Deliberately <b>not</b> wrapped in <see cref="PerCallTimeout"/>-style swallowing: unlike
/// a failed expand, a failed or refused rebirth is something the operator must see, so the
/// exception propagates to the caller for display.
/// </para>
/// </remarks>
// The authorization check is the point of routing this through the service at all.
// Every other member here is read-only; this one causes the browse session to publish onto
// a live plant broker, so it is gated on the same DriverOperator policy the picker
// bodies evaluate before rendering their Browse affordance. A render-time check alone is
// not a control — it decides what a page draws, not what a circuit may invoke — so the
// check is made here, where the action actually happens, and it fails closed.
// Deliberately not wrapped in -style swallowing: unlike
// a failed expand, a failed or refused rebirth is something the operator must see, so the
// exception propagates to the caller for display.
public async Task<int> RequestRebirthAsync(Guid token, string scope, CancellationToken ct)
{
if (!registry.TryGet(token, out var session))
@@ -1,7 +1,7 @@
namespace ZB.MOM.WW.OtOpcUa.AdminUI.Browsing;
/// <summary>
/// Validates an operator-typed Sparkplug rebirth scope for the raw browse modal (Gitea #514).
/// Validates an operator-typed Sparkplug rebirth scope for the raw browse modal.
/// </summary>
/// <remarks>
/// <para>
@@ -29,5 +29,6 @@ public sealed class ContextMenuItem
public bool IsSeparator { get; init; }
/// <summary>A horizontal divider between groups of items.</summary>
/// <returns>A separator menu item.</returns>
public static ContextMenuItem Separator() => new() { IsSeparator = true };
}
@@ -5,7 +5,7 @@ namespace ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared;
/// </summary>
/// <remarks>
/// <para>
/// <b>Why this exists (#504).</b> Several pages abbreviated a hash / thumbprint with the range
/// <b>Why this exists.</b> Several pages abbreviated a hash / thumbprint with the range
/// operator — <c>@s.SourceHash[..12]…</c> — which throws
/// <see cref="ArgumentOutOfRangeException"/> the moment the value is shorter than the slice.
/// In Blazor that escapes <c>BuildRenderTree</c> unhandled and takes the <b>whole page</b> to an
@@ -4,7 +4,7 @@ using System.Text.Json.Nodes;
namespace ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers;
/// <summary>
/// Preserve-unknown save for the typed driver forms (#576). A form deserialises the stored DriverConfig
/// Preserve-unknown save for the typed driver forms. A form deserialises the stored DriverConfig
/// into a typed options object and re-serialises it on save, which erases every key the type does not
/// model (a newer option, a hand-edited key, <c>rawTags</c>, a device's extra keys…). This overlays only
/// the paths the form OWNS onto the ORIGINAL JSON object: an owned path is replaced by the form's value,
@@ -16,9 +16,10 @@ internal static class DriverConfigJsonOverlay
/// <param name="originalJson">The stored config as loaded; blank or non-object input yields <paramref name="typedJson"/> unchanged.</param>
/// <param name="typedJson">The form's own serialised options.</param>
/// <param name="ownedPaths">Dot-separated, case-insensitive property paths the form edits (e.g. <c>transport</c>, <c>probe.enabled</c>).</param>
/// <returns>The merged JSON document.</returns>
/// <param name="timeSpanToMs">
/// (TimeSpan-string path, integer-millisecond path) pairs. The typed options serialise durations as
/// <c>"00:00:05"</c> but the driver factories bind <c>*Ms</c> integers (#576); each pair is rewritten
/// <c>"00:00:05"</c> but the driver factories bind <c>*Ms</c> integers; each pair is rewritten
/// in the typed output (and the legacy TimeSpan path becomes owned, so a stale one is removed).
/// </param>
public static string Apply(string? originalJson, string typedJson, IEnumerable<string> ownedPaths,
@@ -4,13 +4,16 @@ using System.Text.Json.Nodes;
namespace ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers;
/// <summary>
/// Shared millisecond helpers for the AB forms (#576): the driver factories bind <c>*Ms</c> integers
/// Shared millisecond helpers for the AB forms: the driver factories bind <c>*Ms</c> integers
/// while the forms edit whole seconds, so a sub-second stored value must survive an edit of an
/// unrelated field.
/// </summary>
internal static class DriverConfigMs
{
/// <summary>Reads an integer-millisecond key at <paramref name="path"/> from <paramref name="json"/>, or null.</summary>
/// <param name="json">The driver config JSON, which may be null or blank.</param>
/// <param name="path">The dot-separated key path to read.</param>
/// <returns>The integer value, or null when the key is absent or not an integer.</returns>
public static int? Read(string? json, string path)
{
if (string.IsNullOrWhiteSpace(json)) return null;
@@ -27,13 +30,18 @@ internal static class DriverConfigMs
catch (JsonException) { return null; }
}
/// <summary>Whole seconds for display (truncating, like the pre-#576 forms).</summary>
/// <summary>Whole seconds for display (truncating, like the earlier forms).</summary>
/// <param name="t">The duration to convert.</param>
/// <returns>The whole seconds in <paramref name="t"/>.</returns>
public static int ToSeconds(TimeSpan t) => (int)t.TotalSeconds;
/// <summary>
/// The duration to save: the loaded value when the operator left the seconds field unchanged
/// (keeps 500 ms from collapsing to 0 s), else the edited whole seconds.
/// </summary>
/// <param name="seconds">The whole seconds currently shown in the form.</param>
/// <param name="loaded">The duration originally loaded from config, if any.</param>
/// <returns>The duration to persist.</returns>
public static TimeSpan Save(int seconds, TimeSpan? loaded)
=> loaded is { } l && ToSeconds(l) == seconds ? l : TimeSpan.FromSeconds(seconds);
}
@@ -31,7 +31,7 @@ namespace ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers.Forms;
/// </para>
/// <para>
/// <b>Preserving what this form does not author.</b> The inbound blob's keys are retained in a bag
/// and the typed fields are written over it, so (a) the <c>Sparkplug</c> sub-object — P2, Task 21+ —
/// and the typed fields are written over it, so (a) the <c>Sparkplug</c> sub-object (a later phase)
/// survives a load→save untouched, and (b) any key a newer driver adds is not silently dropped by an
/// older AdminUI. <c>RawTags</c> is the one key deliberately REMOVED: the deploy artifact injects it
/// via <c>DriverDeviceConfigMerger</c>, and a form-authored copy would be dead weight.
@@ -149,7 +149,7 @@ public sealed class MqttDriverFormModel
public string SparkplugHostId { get; set; } = "";
/// <summary>
/// Sparkplug mode: claim the Primary Host Application role (Gitea #511) — a retained
/// Sparkplug mode: claim the Primary Host Application role — a retained
/// <c>ONLINE</c>, a matching <c>OFFLINE</c> armed as the MQTT Last Will, and an explicit
/// <c>OFFLINE</c> on clean shutdown.
/// </summary>
@@ -2,7 +2,7 @@ namespace ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers.Forms;
/// <summary>
/// The rule deciding which primary-host advisory <c>MqttDriverForm</c> shows when
/// <c>Act as Primary Host</c> is on (Gitea #511).
/// <c>Act as Primary Host</c> is on.
/// </summary>
/// <remarks>
/// <para>
@@ -20,7 +20,7 @@ public enum FocasManualAddressKind
Macro,
/// <summary>
/// A selector over the CNC's active alarm list (<c>ALARM:</c>, Gitea #647). Only useful on a tag that also
/// A selector over the CNC's active alarm list (<c>ALARM:</c>). Only useful on a tag that also
/// carries the native-alarm object — the pair is what becomes a Part 9 condition.
/// </summary>
Alarm,
@@ -40,7 +40,7 @@ public enum FocasManualAddressKind
/// <c>axis/spindle/program/status</c> — none of which is a FOCAS addressing space — so the
/// picker's own default value, <c>axis:5</c>, was an address the driver rejects. Together with
/// the browse-commit defect this meant every UI-assisted authoring path produced unusable tags,
/// and only hand-typed addresses worked at all (Gitea #540).
/// and only hand-typed addresses worked at all.
/// </para>
/// </remarks>
public static class FocasAddressBuilder
@@ -23,7 +23,7 @@ public sealed class ResilienceFormModel
public static readonly string[] Capabilities =
["Read", "Write", "Discover", "Subscribe", "Probe", "AlarmSubscribe", "AlarmAcknowledge", "Initialize"];
// RecycleIntervalSeconds is GONE (Gitea #522) — the scheduled-recycle machinery it authored was
// RecycleIntervalSeconds is GONE — the scheduled-recycle machinery it authored was
// deleted, so the field configured nothing. It is deliberately NOT explicitly stripped from stored
// JSON: the model's preserve-unknown-keys contract now covers it, so an existing blob's
// "recycleIntervalSeconds" survives an unrelated edit in _bag rather than being silently dropped,
@@ -71,15 +71,15 @@ public static class EndpointRouteBuilderExtensions
services.AddScoped<Browsing.IBrowserSessionService, Browsing.BrowserSessionService>();
services.AddScoped<IUnsTreeService, UnsTreeService>();
services.AddScoped<IRawTreeService, RawTreeService>();
// v3 Batch 3 (WP2): authoring-time UNS effective-name uniqueness guard. Consumed by
// UnsTreeService's reference/VirtualTag/ScriptedAlarm mutations (WP1); mirrors the
// v3 Batch 3: authoring-time UNS effective-name uniqueness guard. Consumed by
// UnsTreeService's reference/VirtualTag/ScriptedAlarm mutations; mirrors the
// deploy-time DraftValidator UnsEffectiveNameCollision rule.
services.AddScoped<IEffectiveNameGuard, EffectiveNameGuard>();
// #520 stage 7: the ACL scope picker's two trees + the authoring-time scope/principal checks that
// the ACL scope picker's two trees + the authoring-time scope/principal checks that
// mirror the deploy gate's NodeAclScope* rules. Scoped, because it composes the two scoped tree
// services above.
services.AddScoped<Acls.IAclScopeService, Acls.AclScopeService>();
// WP5 CSV export enumeration (read-only; does not extend the closed IRawTreeService prelude).
// CSV export enumeration (read-only; does not extend the closed IRawTreeService prelude).
services.AddScoped<RawTagCsvExportReader>();
services.AddSingleton<IDriverBrowser, OpcUaClientDriverBrowser>();
services.AddSingleton<IDriverBrowser, GalaxyDriverBrowser>();
@@ -30,7 +30,7 @@ namespace ZB.MOM.WW.OtOpcUa.AdminUI.Grpc;
/// </para>
/// <para>
/// <b>NotFound is indistinguishable across two cases</b> — unknown id and an empty blob. The
/// first is existence-hiding; the second is the #485 rule (a zero-length artifact is "no
/// first is existence-hiding; the second is the empty-artifact rule (a zero-length artifact is "no
/// answer," never "a configuration with no drivers"). Streaming empty bytes as if valid is
/// exactly what that defect class forbids.
/// </para>
@@ -74,7 +74,7 @@ public sealed class DeploymentArtifactGrpcService : GeneratedServiceBase
.Select(d => new { d.ArtifactBlob })
.FirstOrDefaultAsync(context.CancellationToken);
// Existence-hiding + #485: unknown id / empty blob collapse to one NotFound. Status is NOT
// Existence-hiding + the empty-artifact rule: unknown id / empty blob collapse to one NotFound. Status is NOT
// gated — a node fetches during apply, before the deployment is sealed (see the class remarks).
if (row is null || row.ArtifactBlob.Length == 0)
{
@@ -51,11 +51,11 @@ public sealed record HostsDriverInstanceInfo(
/// <param name="SkippedTags">Authored tags the driver could not build into its poll table; null when there
/// is no answer — the driver cannot report skips, or it faulted before building a tag table. Lets
/// "ignoring 20 of 22 tags" show even while every other column on the row — state, last read, error
/// count, last error — reads perfectly healthy (Gitea #541).</param>
/// count, last error — reads perfectly healthy.</param>
/// <param name="Diagnostics">Driver-reported diagnostics (e.g. S7 negotiated PDU size); null or empty when
/// the driver has none to show (Gitea #640).</param>
/// the driver has none to show.</param>
/// <param name="Enabled">Whether the matching configured instance is authored enabled; <see langword="true"/>
/// when no instance matched. Fed to the row's expandable <c>DriverStatusPanel</c> (Gitea #546). An
/// when no instance matched. Fed to the row's expandable <c>DriverStatusPanel</c>. An
/// unmatched row defaults to enabled on purpose: the row only exists because a live snapshot arrived,
/// so telling the operator it is "not deployed" would contradict the evidence in front of them.</param>
public sealed record HostsDriverRow(
@@ -60,10 +60,10 @@ public sealed class InProcessBroadcaster<T> : IInProcessBroadcaster<T>
private readonly object _connectionLock = new();
private bool _isConnected;
/// <inheritdoc />
/// <summary>Raised once per <see cref="Publish"/> with the published item, on the caller's thread.</summary>
public event Action<T>? Received;
/// <inheritdoc />
/// <summary>Raised whenever <see cref="IsConnected"/> changes, with the new value, on the caller's thread.</summary>
public event Action<bool>? ConnectionStateChanged;
/// <inheritdoc />
@@ -11,7 +11,7 @@ public sealed class InMemoryDriverResilienceStatusStore : IDriverResilienceStatu
{
private readonly ConcurrentDictionary<(string Instance, string Host), DriverResilienceStatusChanged> _byPair = new();
/// <inheritdoc />
/// <summary>Raised after every <see cref="Upsert"/> with the just-stored snapshot.</summary>
public event Action<DriverResilienceStatusChanged>? SnapshotChanged;
/// <inheritdoc />
@@ -11,7 +11,7 @@ public sealed class InMemoryDriverStatusSnapshotStore : IDriverStatusSnapshotSto
{
private readonly ConcurrentDictionary<string, DriverHealthChanged> _byInstance = new();
/// <inheritdoc />
/// <summary>Raised whenever a driver status snapshot is stored or updated.</summary>
public event Action<DriverHealthChanged>? SnapshotChanged;
/// <inheritdoc />
@@ -100,6 +100,7 @@ public sealed class ManualFailoverPageModel
/// Performs the failover the dialog is confirming.
/// </summary>
/// <param name="actor">The authenticated user name, recorded in the audit event.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public async Task ConfirmFailoverAsync(string actor)
{
if (!ConfirmOpen) return;
@@ -55,7 +55,7 @@ public sealed record ScriptTagInfo(string Path, string Kind, string DataType, st
/// (<c>DriverHostActor._nodeIdByDriverRef</c> is keyed <c>(DriverInstanceId, RawPath)</c>).
/// </para>
/// <para>
/// <b>This replaced a stale v2 projection (Gitea #490).</b> The catalog used to emit
/// <b>This replaced a stale v2 projection.</b> The catalog used to emit
/// <c>Tag.TagConfig.FullName</c> — the pre-v3 wire address — which since v3 is <i>not</i> the mux
/// key. The consequence was worse than the missing feature the issue reported: completion offered
/// paths that could never resolve at runtime, while a <b>correct</b> absolute RawPath got no
@@ -35,13 +35,11 @@ public sealed class EffectiveNameGuard(IDbContextFactory<OtOpcUaConfigDbContext>
return FirstCollision(nameSpace, proposedEffectiveName, kind, excludeSourceId, equipmentId);
}
// The whole point of the batch entry point: ONE context and ONE load of the equipment's name
// space, then every proposed name tested in memory against it - the per-name rules and message
// text come from the same FirstCollision helper CheckAsync uses, so the two can never drift. A
// batch is a create of N new rows, so there is no self-row to exclude.
/// <inheritdoc />
/// <remarks>
/// The whole point of the batch entry point: ONE context and ONE load of the equipment's name
/// space, then every proposed name tested in memory against it — the per-name rules and message
/// text come from the same <see cref="FirstCollision"/> helper <see cref="CheckAsync"/> uses, so
/// the two can never drift. A batch is a create of N new rows, so there is no self-row to exclude.
/// </remarks>
public async Task<string?> CheckManyAsync(
string equipmentId,
IReadOnlyList<string> proposedEffectiveNames,
@@ -3,8 +3,8 @@ using ZB.MOM.WW.OtOpcUa.Configuration.Enums;
namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns;
/// <summary>
/// Detached, editable projection of a raw <c>Tag</c> — the read side of tag editing. WP1 exposes this
/// loader; WP4 owns the create/update authoring surface and should align its input model with these
/// Detached, editable projection of a raw <c>Tag</c> — the read side of tag editing. The create/update
/// authoring surface should align its input model with these
/// fields (identity is the RawPath, formed from the tag's device + optional group + name).
/// </summary>
/// <param name="TagId">The tag's stable logical id.</param>
@@ -30,7 +30,7 @@ public readonly record struct RawTagEditDto(
byte[] RowVersion);
/// <summary>
/// Detached, editable projection of a <c>DriverInstance</c> — the read side of the Wave-B (WP3)
/// Detached, editable projection of a <c>DriverInstance</c> — the read side of the
/// "Configure driver" modal. <c>DriverType</c> is included so the modal can dispatch to the correct
/// typed driver-config editor; it is immutable, so <see cref="IRawTreeService.UpdateDriverAsync"/> does
/// not change it.
@@ -50,7 +50,7 @@ public sealed record RawDriverEditDto(
byte[] RowVersion);
/// <summary>
/// Detached, editable projection of a <c>Device</c> — the read side of the Wave-B (WP3) "Configure
/// Detached, editable projection of a <c>Device</c> — the read side of the "Configure
/// device" modal. <c>DriverType</c> is joined in from the parent <c>DriverInstance</c> so the modal can
/// dispatch to the correct typed device-config editor (endpoint/connection settings now live in
/// <c>DeviceConfig</c>).
@@ -76,14 +76,14 @@ public sealed record RawDeviceEditDto(
/// Enterprise → Cluster → Folder → Driver → Device → TagGroup → Tag hierarchy — from the config
/// database. The peer of <see cref="IUnsTreeService"/> for the Raw subtree.
/// <para>
/// <b>Contract split (Batch 2 Wave A):</b> this file's committed surface is the <b>read</b> contract
/// <b>Contract split:</b> this file's committed surface is the <b>read</b> contract
/// the <c>RawTree</c> component consumes — <see cref="LoadRootsAsync"/> (eager Enterprise→Cluster roots)
/// and <see cref="LoadChildrenAsync"/> (one lazy level per expand). B2-WP1 (<c>RawTreeService</c>)
/// and <see cref="LoadChildrenAsync"/> (one lazy level per expand). <c>RawTreeService</c>
/// <b>extends this interface</b> with the mutation surface — create/rename/delete per node type,
/// move-into-folder, and the per-node edit projections — enforcing the integrity rules with
/// user-readable errors (a delete blocked by a <c>UnsTagReference</c> names the referencing equipment).
/// Rename methods return <see cref="RawRenameResult"/> so the UI can show non-blocking warnings.
/// Mutations reuse <see cref="UnsMutationResult"/>. WP2 must not add to this interface.
/// Mutations reuse <see cref="UnsMutationResult"/>. Do not add to this interface from other services.
/// </para>
/// </summary>
public interface IRawTreeService
@@ -105,7 +105,7 @@ public interface IRawTreeService
/// yields its Devices; a Device yields its root TagGroups + Tags; a TagGroup yields sub-TagGroups
/// + Tags. Tags are leaves and yield nothing. Ordering is deterministic and ordinal. Reads
/// untracked; returns detached nodes. Per-device tag counts can be large — the implementation may
/// page, but the committed shape returns the level's nodes (paging knobs, if any, are WP1's to add
/// page, but the committed shape returns the level's nodes (paging knobs, if any, belong
/// on the concrete type without changing this signature's meaning for the tree).
/// </summary>
/// <param name="parent">The container node whose direct children to load.</param>
@@ -167,7 +167,7 @@ public interface IRawTreeService
/// <summary>
/// Creates a minimal driver instance and its auto-created default <c>Device</c> so the tree has a
/// child to show. Full typed driver/device config authoring is Wave B (WP3) — this create takes the
/// child to show. Full typed driver/device config authoring is not done here — this create takes the
/// driver config JSON verbatim and seeds an empty (<c>{}</c>) default device. The driver name is a
/// RawPath segment, unique among its cluster/folder siblings.
/// </summary>
@@ -175,7 +175,7 @@ public interface IRawTreeService
/// <param name="folderId">The containing folder's logical id, or null for a cluster-root driver.</param>
/// <param name="name">The driver instance name (a RawPath segment).</param>
/// <param name="driverType">The driver-type string (see <c>DriverTypeNames</c>).</param>
/// <param name="driverConfigJson">The driver config JSON blob (opaque here; validated in Wave B).</param>
/// <param name="driverConfigJson">The driver config JSON blob (opaque here; validated by the typed editors).</param>
/// <param name="ct">A token to cancel the operation.</param>
/// <returns>The create outcome; <c>CreatedId</c> is the new <c>DriverInstanceId</c> on success.</returns>
Task<UnsMutationResult> CreateDriverAsync(string clusterId, string? folderId, string name, string driverType, string driverConfigJson, CancellationToken ct = default);
@@ -212,13 +212,13 @@ public interface IRawTreeService
// --- Device mutations ---
/// <summary>
/// Creates a minimal <c>Device</c> under a driver. Full typed device-config authoring is Wave B
/// (WP3) — this create takes the device config JSON verbatim. The device name must be unique among
/// Creates a minimal <c>Device</c> under a driver. Full typed device-config authoring is not done here
/// — this create takes the device config JSON verbatim. The device name must be unique among
/// the driver's devices.
/// </summary>
/// <param name="driverInstanceId">The owning driver instance's logical id.</param>
/// <param name="name">The device name (a RawPath segment).</param>
/// <param name="deviceConfigJson">The device config JSON blob (opaque here; validated in Wave B).</param>
/// <param name="deviceConfigJson">The device config JSON blob (opaque here; validated by the typed editors).</param>
/// <param name="ct">A token to cancel the operation.</param>
/// <returns>The create outcome; <c>CreatedId</c> is the new <c>DeviceId</c> on success.</returns>
Task<UnsMutationResult> CreateDeviceAsync(string driverInstanceId, string name, string deviceConfigJson, CancellationToken ct = default);
@@ -272,7 +272,7 @@ public interface IRawTreeService
/// <returns>The delete outcome.</returns>
Task<UnsMutationResult> DeleteTagGroupAsync(string tagGroupId, byte[] rowVersion, CancellationToken ct = default);
// --- Tag mutations / projections (create + update are WP4) ---
// --- Tag mutations / projections ---
/// <summary>
/// Deletes a raw <c>Tag</c>. Blocked while any <c>UnsTagReference</c> points at it; the failure
@@ -285,9 +285,9 @@ public interface IRawTreeService
Task<UnsMutationResult> DeleteTagAsync(string tagId, byte[] rowVersion, CancellationToken ct = default);
/// <summary>
/// Loads a raw tag's editable fields as a detached projection. WP1 provides the read-only projection;
/// the create/update authoring surface is WP4 (which should align its input shape with
/// <see cref="RawTagEditDto"/>).
/// Loads a raw tag's editable fields as a detached projection. The create/update authoring
/// surface should align its input shape with
/// <see cref="RawTagEditDto"/>.
/// </summary>
/// <param name="tagId">The tag's logical id.</param>
/// <param name="ct">A token to cancel the load.</param>
@@ -322,7 +322,7 @@ public interface IRawTreeService
Task<UnsMutationResult> UpdateTagAsync(string tagId, RawTagInput input, byte[] rowVersion, CancellationToken ct = default);
/// <summary>
/// Commits a batch of raw tags under a device — the WP5 CSV-import path. Each row's
/// Commits a batch of raw tags under a device — the CSV-import path. Each row's
/// <c>TagGroupPath</c> is a <c>/</c>-separated tag-group path under the device whose segments are
/// auto-created as nested <c>TagGroup</c>s (reusing existing ones). Per-row validation errors (bad
/// name segment, malformed <c>TagConfig</c> JSON, a duplicate name within the device+group) are
@@ -337,7 +337,7 @@ public interface IRawTreeService
Task<RawTagImportResult> ImportTagsAsync(string deviceId, IReadOnlyList<RawTagImportRow> rows, CancellationToken ct = default);
/// <summary>
/// Loads a driver instance's editable fields as a detached projection for the WP3 "Configure driver"
/// Loads a driver instance's editable fields as a detached projection for the "Configure driver"
/// modal. <c>DriverType</c> is included for typed-editor dispatch (it is immutable).
/// </summary>
/// <param name="driverInstanceId">The driver instance's logical id.</param>
@@ -346,7 +346,7 @@ public interface IRawTreeService
Task<RawDriverEditDto?> LoadDriverForEditAsync(string driverInstanceId, CancellationToken ct = default);
/// <summary>
/// Updates a driver instance's name + config from the WP3 "Configure driver" modal. The name is
/// Updates a driver instance's name + config from the "Configure driver" modal. The name is
/// validated as a sibling-unique RawPath segment (same scope as <see cref="RenameDriverAsync"/>);
/// last-write-wins on <paramref name="rowVersion"/>. <c>DriverType</c> is immutable and is not changed.
/// </summary>
@@ -360,7 +360,7 @@ public interface IRawTreeService
Task<UnsMutationResult> UpdateDriverAsync(string driverInstanceId, string name, string driverConfigJson, string? resilienceConfig, byte[] rowVersion, CancellationToken ct = default);
/// <summary>
/// Loads a device's editable fields as a detached projection for the WP3 "Configure device" modal.
/// Loads a device's editable fields as a detached projection for the "Configure device" modal.
/// <c>DriverType</c> is joined in from the parent driver so the modal can dispatch to the correct typed
/// device-config editor.
/// </summary>
@@ -370,7 +370,7 @@ public interface IRawTreeService
Task<RawDeviceEditDto?> LoadDeviceForEditAsync(string deviceId, CancellationToken ct = default);
/// <summary>
/// Updates a device's name + config + enabled state from the WP3 "Configure device" modal. The name
/// Updates a device's name + config + enabled state from the "Configure device" modal. The name
/// is validated as a RawPath segment unique among the driver's devices; last-write-wins on
/// <paramref name="rowVersion"/>.
/// </summary>
@@ -387,7 +387,7 @@ public interface IRawTreeService
/// Builds the single merged config blob the driver-probe (test-connect) path binds from for one device:
/// the parent driver's <c>DriverConfig</c> folded together with this device's <c>DeviceConfig</c> (via
/// <c>DriverDeviceConfigMerger</c>, endpoint keys merging up from <c>DeviceConfig</c>). Used by the
/// "Test connect" button inside the WP3 driver/device modals now that the endpoint lives in
/// "Test connect" button inside the driver/device modals now that the endpoint lives in
/// <c>DeviceConfig</c>.
/// </summary>
/// <param name="deviceId">The device to probe.</param>
@@ -12,7 +12,7 @@ using ZB.MOM.WW.OtOpcUa.Driver.Mqtt;
namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns;
/// <summary>
/// Pure mapper for the WP6 "Browse device…" re-target: turns a selected driver-browse leaf into a
/// Pure mapper for the "Browse device…" re-target: turns a selected driver-browse leaf into a
/// <see cref="RawTagImportRow"/> ready for <see cref="IRawTreeService.ImportTagsAsync"/>. Under the v3
/// identity contract the tag's identity is its RawPath (device + optional group + name), so the leaf's
/// driver reference is written into the driver-typed <c>TagConfig</c> as an ordinary <b>address field</b>
@@ -30,7 +30,7 @@ public static class RawBrowseCommitMapper
/// captured <c>DriverAttributeInfo.FullName</c>) — becomes the driver-typed address field.</param>
/// <param name="browseName">The leaf's browse name. Becomes the raw tag <c>Name</c> after
/// <see cref="ToRawSegment"/> coerces it into a legal RawPath segment — a Sparkplug metric name
/// legitimately contains <c>/</c> and a Name may not (Gitea #509). The leaf's binding address is
/// legitimately contains <c>/</c> and a Name may not. The leaf's binding address is
/// unaffected: it travels separately into the <c>TagConfig</c>.</param>
/// <param name="driverDataType">The leaf's <see cref="DriverDataType"/> name (from the browse
/// attribute side-channel), or null when the browser cannot report a type (e.g. the OPC UA Client tree).</param>
@@ -72,7 +72,7 @@ public static class RawBrowseCommitMapper
}
/// <summary>
/// Coerces a browse leaf's name into a legal RawPath segment (Gitea #509): trims the ends and
/// Coerces a browse leaf's name into a legal RawPath segment: trims the ends and
/// replaces every <see cref="RawPaths.Separator"/> with <see cref="SeparatorReplacement"/>.
/// </summary>
/// <param name="browseName">The leaf's browse name, as the driver reported it.</param>
@@ -122,7 +122,7 @@ public static class RawBrowseCommitMapper
/// <returns>One operator-facing message per colliding set; empty when there is nothing to refuse.</returns>
/// <remarks>
/// Sanitising maps many names onto one — <c>A/B</c> and <c>A_B</c> both become <c>A_B</c> — and a
/// silent collision is materially worse than the refusal #509 replaced: two distinct metrics would
/// silent collision is materially worse than the refusal it replaced: two distinct metrics would
/// become one tag bound to whichever address the import happened to keep. So the coercion is only
/// safe when paired with this check.
/// <para>
@@ -205,7 +205,7 @@ public static class RawBrowseCommitMapper
/// <b>The data type is not optional decoration for AB CIP / TwinCAT / FOCAS</b> — their tag-definition
/// factories decode the wire bytes by this field, not by the raw tag row's OPC UA <c>DataType</c>. A
/// committed leaf left at the model default therefore reads real data through the wrong decoder and
/// publishes a plausible wrong number rather than an error (Gitea #536).
/// publishes a plausible wrong number rather than an error.
/// </para>
/// <para>
/// <b>MQTT is the one driver whose address is not a single string</b> — a Sparkplug tag binds by a
@@ -214,13 +214,13 @@ public static class RawBrowseCommitMapper
/// </para>
/// <para>
/// <b>MTConnect binds by the driver-AGNOSTIC type, so it is forwarded from
/// <paramref name="driverDataType"/> rather than from a stated native field</b> (Gitea #560). Its
/// <paramref name="driverDataType"/> rather than from a stated native field</b>. Its
/// coercion type IS a <see cref="DriverDataType"/> — the very enum the browse leaf carries, produced
/// by the driver's own <c>/probe</c> inference — so there is no separate native spelling for the
/// browser to state and nothing to re-derive. Left unforwarded, the model's <c>String</c> default was
/// written as a non-blank authored type, which OUT-RANKS that same inference at the driver: every
/// browsed SAMPLE published text into the numeric node <see cref="MapLeaf"/> had just typed from the
/// identical inference. Same defect class as #536, one door along.
/// identical inference. Same defect class as the type-inference bug above, one door along.
/// </para>
/// </summary>
/// <param name="driverType">The owning device's driver type.</param>
@@ -268,7 +268,7 @@ public static class RawBrowseCommitMapper
// editor's canonical spelling is fullName — committing under the generic key below would open
// in that editor with an EMPTY id field and blank it on save.
//
// The coercion type is the leaf's own inferred DriverDataType (#560) — see the remarks above.
// The coercion type is the leaf's own inferred DriverDataType — see the remarks above.
// A stated native "dataType" address field still wins where a browser supplies one, so this
// branch reads exactly like its AB CIP / TwinCAT / FOCAS siblings; the difference is only that
// MTConnect's fallback is the leaf's inference rather than a fixed model default.
@@ -295,11 +295,11 @@ public static class RawBrowseCommitMapper
// - a driver type with a bespoke IDriverBrowser registered by AddAdminUI() — read back from the
// real registration, not a list — must NOT reach here; and
// - any type that does reach here must be named in that test's GenericKeyExemptions with a reason,
// and every name on that list must still reach here (Gitea #558) — an exemption for a driver
// and every name on that list must still reach here — an exemption for a driver
// that has since gained a branch above is a stale claim, and a silently inert one.
// The universal DiscoveryDriverBrowser's arm is not derivable from the AdminUI assembly (it needs
// the runtime drivers + the Host's IDriverFactory), so it is covered by the exemption list rather
// than mechanically — see the test's remarks for the residual trust that leaves (Gitea #555).
// than mechanically — see the test's remarks for the residual trust that leaves.
return WriteSingleKey("address", address);
}
@@ -383,7 +383,7 @@ public static class RawBrowseCommitMapper
/// <c>BadNodeIdUnknown</c> forever with nothing to point at.
/// </para>
/// <para>
/// <b>Sql</b> (Gitea #552): a column of a table carrying no date/time column. A wide-row tag must say
/// <b>Sql</b>: a column of a table carrying no date/time column. A wide-row tag must say
/// which ROW it reads, and with no timestamp to order by the only remaining selector is a
/// <c>whereColumn</c>/<c>whereValue</c> pair — whose value is <em>data</em>, not schema, and therefore
/// is not something any browse can know. Refusing here rather than letting the import's own gate
@@ -418,7 +418,7 @@ public static class RawBrowseCommitMapper
/// <summary>
/// Describes a Sql column leaf whose wide-row binding cannot be completed from the catalog, or
/// <c>null</c> when it can (Gitea #552).
/// <c>null</c> when it can.
/// </summary>
/// <param name="browseName">The leaf's browse name, for the message.</param>
/// <param name="addressFields">The structured address the browse session stated, if any.</param>
@@ -451,7 +451,7 @@ public static class RawBrowseCommitMapper
/// <param name="fallback">The model default to keep when no usable native type was stated.</param>
/// <returns>The parsed native type, or <paramref name="fallback"/>.</returns>
/// <remarks>
/// <b>The type is READ, never derived (Gitea #536).</b> A commit used to leave this at the
/// <b>The type is READ, never derived.</b> A commit used to leave this at the
/// model default, so every browsed AB CIP leaf — a REAL, a BOOL, a STRING — was written as
/// <c>DInt</c> and the driver decoded four bytes of a float as an integer: a plausible
/// number, no error, wrong value. Deriving it from the leaf's driver-AGNOSTIC
@@ -480,7 +480,7 @@ public static class RawBrowseCommitMapper
/// Parses one stated type NAME into a driver's data-type enum, keeping <paramref name="fallback"/>
/// for anything unusable — the rule <see cref="NativeType{TEnum}"/> applies to a stated address
/// field, split out so a type that arrives by another route (MTConnect's leaf-level
/// <see cref="DriverDataType"/>, Gitea #560) is judged by exactly the same one.
/// <see cref="DriverDataType"/>) is judged by exactly the same one.
/// </summary>
/// <typeparam name="TEnum">The data-type enum the driver's tag config carries.</typeparam>
/// <param name="raw">The stated type name, or null/blank.</param>
@@ -509,7 +509,7 @@ public static class RawBrowseCommitMapper
: null;
/// <summary>
/// Combines a target-group path prefix with an optional mirrored sub-path, matching the WP5 CSV import
/// Combines a target-group path prefix with an optional mirrored sub-path, matching the CSV import
/// combine semantics: blank collapses to null, and a present prefix + suffix join with the RawPath
/// separator. Returns null when both are absent (⇒ commit at the device root).
/// </summary>
@@ -542,10 +542,10 @@ public static class RawBrowseCommitMapper
/// <remarks>
/// <para>
/// <b>A wide-row tag needs three things, not two: the table, the column, and WHICH ROW</b>
/// (Gitea #552). This branch used to emit only the first two, and a selector-less wide-row blob is
/// This branch used to emit only the first two, and a selector-less wide-row blob is
/// refused by <c>SqlEquipmentTagParser</c> and by <c>SqlTagConfigModel.Validate</c> alike — so every
/// browse-committed Sql tag was unreadable, first silently (<c>BadNodeIdUnknown</c> forever) and then,
/// once #551 put the gate on the import, loudly at commit.
/// once the gate was put on the import, loudly at commit.
/// </para>
/// <para>
/// <b>The row selector is READ from the session's stated fields, never inferred here</b> — same rule
@@ -15,10 +15,14 @@ namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns;
public readonly record struct RawRenameResult(bool Ok, string? Error, IReadOnlyList<string> Warnings)
{
/// <summary>A successful rename carrying zero or more advisory warnings.</summary>
/// <param name="warnings">Non-blocking advisories to show after the rename, or <see langword="null"/> for none.</param>
/// <returns>A successful <see cref="RawRenameResult"/>.</returns>
public static RawRenameResult Success(IReadOnlyList<string>? warnings = null) =>
new(true, null, warnings ?? Array.Empty<string>());
/// <summary>A failed rename carrying the operator-facing message.</summary>
/// <param name="error">The operator-facing failure message.</param>
/// <returns>A failed <see cref="RawRenameResult"/>.</returns>
public static RawRenameResult Failure(string error) =>
new(false, error, Array.Empty<string>());
}
@@ -5,9 +5,9 @@ using ZB.MOM.WW.OtOpcUa.Configuration;
namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns;
/// <summary>
/// Read-only enumeration helper for the WP5 CSV export path. Reads a device's tag-groups + tags directly
/// Read-only enumeration helper for the CSV export path. Reads a device's tag-groups + tags directly
/// from the config DB and flattens them (with each tag's reconstructed <c>/</c>-separated
/// <see cref="RawCsvExportTag.TagGroupPath"/>) into the export shape. Owned by WP5 — it does NOT extend
/// <see cref="RawCsvExportTag.TagGroupPath"/>) into the export shape. Owned by the CSV export path — it does NOT extend
/// <see cref="IRawTreeService"/> (that prelude is closed); it takes its own
/// <see cref="IDbContextFactory{TContext}"/> so export never mutates. Also resolves a tag-group's path +
/// owning device (the import modal's target-group prefix seam).
@@ -8,7 +8,7 @@ using ZB.MOM.WW.OtOpcUa.Configuration.Enums;
namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns;
/// <summary>
/// The pure WP5 CSV import/export engine for the Raw tree. Bridges the T0-2 <see cref="CsvParser"/> /
/// The pure CSV import/export engine for the Raw tree. Bridges the <see cref="CsvParser"/> /
/// <see cref="CsvWriter"/> and the per-driver <see cref="CsvColumnMap"/> to the service's
/// <see cref="RawTagImportRow"/> commit shape: <see cref="Parse"/> turns an uploaded CSV into a
/// per-row review model with validation verdicts; <see cref="Export"/> renders a device's tags back to
@@ -20,7 +20,7 @@ namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns;
/// 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
/// The assembled blob is then put to the driver's own <see cref="TagConfigValidator"/>: 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;
@@ -28,8 +28,8 @@ namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns;
/// commit); the guarantee lives in <see cref="IRawTreeService.ImportTagsAsync"/>, which re-runs it.
/// </para>
/// <para>
/// For that gate to mean anything the merge must hand it the row <b>as written</b>, which it did not
/// (Gitea #553): the model-backed maps round-tripped the free-form cell through a driver model's lenient
/// For that gate to mean anything the merge must hand it the row <b>as written</b>, which it did not:
/// the model-backed maps round-tripped the free-form cell through a driver model's lenient
/// <c>FromJson</c>/<c>ToJson</c>, so a typo'd value under a key the model owns was rewritten to that model's
/// default before any gate ran — the row passed, and the tag the operator actually described was gone.
/// <see cref="CsvDriverTagMap.ApplyTypedColumns"/> now preserves the cell's own tokens for every key no
@@ -174,7 +174,7 @@ public static class RawTagCsvMapper
// Every spelling the column speaks for, not just the one it writes: an MTConnect cell
// carrying "driverDataType" is overridden by the MtDataType column exactly as a
// "dataType" cell is, and the operator must see that in the grid (Gitea #553). This
// "dataType" cell is, and the operator must see that in the grid. This
// report is also what makes accepting the override — rather than erroring on the
// contradiction — an open decision instead of a silent one.
if (col.OwnedJsonKeys.Any(baseKeys.Contains))
@@ -217,7 +217,7 @@ 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 driver-typed config gate, on the FINAL assembled blob. 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
@@ -489,6 +489,7 @@ public sealed record RawCsvParseResult(
public bool CanCommit => FatalError is null && Rows.Count > 0 && Rows.All(r => r.Ok);
/// <summary>The valid rows' assembled import rows, ready for <c>ImportTagsAsync</c>.</summary>
/// <returns>The import rows of every valid row.</returns>
public IReadOnlyList<RawTagImportRow> ToImportRows()
=> Rows.Where(r => r is { Ok: true, ImportRow: not null }).Select(r => r.ImportRow!).ToArray();
}
@@ -4,7 +4,7 @@ namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns;
/// <summary>
/// Parameter object carrying the operator-editable fields for a raw <c>Tag</c> create or update in the
/// v3 Raw tree (WP4 manual entry). Identity is the RawPath — the tag's device + optional tag-group +
/// v3 Raw tree (manual entry). Identity is the RawPath — the tag's device + optional tag-group +
/// name — so there is no <c>TagId</c> here: it is generated on create and never carried in the input.
/// Whitespace-only <see cref="PollGroupId"/> collapses to <c>null</c>; <see cref="TagConfig"/> is
/// validated for JSON well-formedness by the service (blank collapses to <c>{}</c>).
@@ -24,7 +24,7 @@ public sealed record RawTagInput(
string TagConfig);
/// <summary>
/// One row of the WP5 CSV import commit. <see cref="TagGroupPath"/> is a <c>/</c>-separated tag-group
/// One row of the CSV import commit. <see cref="TagGroupPath"/> is a <c>/</c>-separated tag-group
/// path under the target device (its segments are auto-created as nested <c>TagGroup</c>s, reusing any
/// that already exist); <c>null</c>/blank places the tag directly under the device. <see cref="Tag"/>
/// carries the tag's editable fields.
@@ -513,7 +513,7 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
});
// Auto-create the default device so a freshly-created driver has a child to show. By design
// (#596): every driver needs at least one device for browse + tags, and DriverDeviceConfigMerger treats
// Every driver needs at least one device for browse + tags, and DriverDeviceConfigMerger treats
// the sole device's DeviceConfig as the endpoint. It is renamable/deletable and carries an empty config.
db.Devices.Add(new Device
{
@@ -620,7 +620,7 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
if (owner is null)
return new UnsMutationResult(false, $"Driver '{driverInstanceId}' not found.");
// #628: MTConnect owns one agent client per driver — mirror the deploy gate
// MTConnect owns one agent client per driver — mirror the deploy gate
// (DraftValidator.ValidateMTConnectSingleDevice) so the second Device is refused where it is authored.
if (string.Equals(owner.DriverType, DriverTypeNames.MTConnect, StringComparison.Ordinal)
&& await db.Devices.AnyAsync(dev => dev.DriverInstanceId == driverInstanceId, ct))
@@ -771,7 +771,7 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
}
// ---------------------------------------------------------------------------------------------
// Tag delete + edit projection (create/update are WP4)
// Tag delete + edit projection (create/update are handled elsewhere)
// ---------------------------------------------------------------------------------------------
/// <inheritdoc />
@@ -823,7 +823,7 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
}
// ---------------------------------------------------------------------------------------------
// Tag create / update (WP4) + CSV import (WP5)
// Tag create / update + CSV import
// ---------------------------------------------------------------------------------------------
/// <inheritdoc />
@@ -928,7 +928,7 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
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).
// one driver, so every row in the batch is judged by the same driver's rules.
var driverType = await ResolveDriverTypeAsync(db, deviceId, ct);
// Existing groups on the device: a (parent-group-id | null, name) → group-id lookup we extend with
@@ -1071,7 +1071,7 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
}
// ---------------------------------------------------------------------------------------------
// Driver config (WP3 "Configure driver")
// Driver config ("Configure driver")
// ---------------------------------------------------------------------------------------------
/// <inheritdoc />
@@ -1126,7 +1126,7 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
}
// ---------------------------------------------------------------------------------------------
// Device config (WP3 "Configure device") + merged probe config (Test connect)
// Device config ("Configure device") + merged probe config (Test connect)
// ---------------------------------------------------------------------------------------------
/// <inheritdoc />
@@ -1255,7 +1255,7 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
/// <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).
/// create, update and bulk import alike.
/// <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
@@ -1288,10 +1288,12 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
{
public static readonly GroupKeyComparer Instance = new();
/// <inheritdoc />
public bool Equals((string? Parent, string Name) x, (string? Parent, string Name) y) =>
string.Equals(x.Parent, y.Parent, StringComparison.Ordinal)
&& string.Equals(x.Name, y.Name, StringComparison.Ordinal);
/// <inheritdoc />
public int GetHashCode((string? Parent, string Name) obj) =>
HashCode.Combine(
obj.Parent is null ? 0 : StringComparer.Ordinal.GetHashCode(obj.Parent),
@@ -1303,10 +1305,12 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
{
public static readonly TagKeyComparer Instance = new();
/// <inheritdoc />
public bool Equals((string? GroupId, string Name) x, (string? GroupId, string Name) y) =>
string.Equals(x.GroupId, y.GroupId, StringComparison.Ordinal)
&& string.Equals(x.Name, y.Name, StringComparison.Ordinal);
/// <inheritdoc />
public int GetHashCode((string? GroupId, string Name) obj) =>
HashCode.Combine(
obj.GroupId is null ? 0 : StringComparer.Ordinal.GetHashCode(obj.GroupId),
@@ -16,14 +16,14 @@ public sealed class AbCipTagConfigModel
/// <summary>Logix atomic type, or <c>AbCipDataType.Structure</c> for UDT-typed tags.</summary>
public AbCipDataType DataType { get; set; } = AbCipDataType.DInt;
/// <summary>Optional writable flag (R2-11); <c>null</c> ⇒ omitted (driver default true), explicit
/// <summary>Optional writable flag; <c>null</c> ⇒ omitted (driver default true), explicit
/// <c>false</c> ⇒ read-only. Preserved across load→save.</summary>
public bool? Writable { get; set; }
private JsonObject _bag = new();
// The blob this model was LOADED FROM, or null when built by object initialiser — the input to the
// Gitea #554 parse consult (see TagConfigParseGate).
// Parse consult (see TagConfigParseGate).
private string? _source;
/// <summary>Loads a model from a TagConfig JSON string, defaulting any absent field and retaining
@@ -63,9 +63,9 @@ public sealed class AbCipTagConfigModel
/// <c>TryReadEnumStrict</c> — a present-but-invalid string rejects the whole tag at the driver
/// (<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).
/// into a tag the driver skips.
/// <para>
/// <b>Declared UDT members are checked too (Gitea #551), and the rule is not restated here.</b>
/// <b>Declared UDT members are checked too, 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>
@@ -86,9 +86,9 @@ public sealed class AbCipTagConfigModel
return memberError;
}
// Gitea #554 backstop. The three checks above already mirror the whole of the reader's rejection
// Backstop. The three checks above already mirror the whole of the reader's rejection
// surface, so this is expected to be silent for AbCip — it is here so a future reader rule cannot
// become a gap without anyone noticing, which is the failure #549/#551 kept repeating.
// become a gap without anyone noticing, which is the failure that kept repeating.
return TagConfigParseGate.Describe(
_source,
j => AbCipTagDefinitionFactory.FromTagConfig(j, TagConfigParseGate.AuthoringRawPath, out _),
@@ -16,14 +16,14 @@ public sealed class AbLegacyTagConfigModel
/// <summary>PCCC data type that maps onto SLC / MicroLogix / PLC-5 files.</summary>
public AbLegacyDataType DataType { get; set; } = AbLegacyDataType.Int;
/// <summary>Optional writable flag (R2-11); <c>null</c> ⇒ omitted (driver default true), explicit
/// <summary>Optional writable flag; <c>null</c> ⇒ omitted (driver default true), explicit
/// <c>false</c> ⇒ read-only. Preserved across load→save.</summary>
public bool? Writable { get; set; }
private JsonObject _bag = new();
// The blob this model was LOADED FROM, or null when built by object initialiser — the input to the
// Gitea #554 parse consult (see TagConfigParseGate).
// Parse consult (see TagConfigParseGate).
private string? _source;
/// <summary>Loads a model from a TagConfig JSON string, defaulting any absent field and retaining
@@ -63,8 +63,7 @@ public sealed class AbLegacyTagConfigModel
// Strict enum, read from the ORIGINAL key bag: AbLegacyTagDefinitionFactory reads "dataType" with
// TryReadEnumStrict, so a present-but-invalid string rejects the whole tag at the driver
// (BadNodeIdUnknown) while the lenient load above would default it to Int. Accepting it here would
// let the CSV-import and API paths — which save the blob verbatim — deploy an unreadable tag
// (Gitea #549).
// let the CSV-import and API paths — which save the blob verbatim — deploy an unreadable tag.
if (TagConfigJson.DescribeInvalidEnum<AbLegacyDataType>(_bag, "dataType") is { } dtError)
return dtError;
@@ -74,7 +73,7 @@ public sealed class AbLegacyTagConfigModel
if (AbLegacyAddress.Validate(Address, family: null) is { } addressError)
return addressError;
// DELIBERATELY STRICTER THAN THE RUNTIME, and re-confirmed as such by the Gitea #554 survey — do not
// DELIBERATELY STRICTER THAN THE RUNTIME, and re-confirmed as such by the parse-gate survey — do not
// "align" it. PCCC data-file elements are limited to AbLegacyArray.MaxElements (256). The reader
// CLAMPS an authored length above that (Math.Min) and serves the tag, but the driver-agnostic
// materialiser sets OPC UA ArrayDimensions from the RAW authored length, so the served array is
@@ -88,7 +87,7 @@ public sealed class AbLegacyTagConfigModel
if (isArray && arrayLength > AbLegacyArray.MaxElements)
return $"AbLegacy array length cannot exceed {AbLegacyArray.MaxElements} (PCCC data-file element limit).";
// Gitea #554 backstop: the checks above mirror the reader's whole rejection surface today, so this is
// Parse-gate backstop: the checks above mirror the reader's whole rejection surface today, so this is
// expected to be silent for AbLegacy. It is here so a future reader rule cannot become a gap.
return TagConfigParseGate.Describe(
_source,
@@ -23,7 +23,7 @@ public sealed class CalculationTagConfigModel
private JsonObject _bag = new();
// The blob this model was LOADED FROM, or null when built by object initialiser — the input to the
// Gitea #554 parse consult (see TagConfigParseGate).
// parse consult (see TagConfigParseGate).
private string? _source;
/// <summary>Loads a model from a TagConfig JSON string, defaulting any absent field and retaining every
@@ -64,7 +64,7 @@ public sealed class CalculationTagConfigModel
/// must be set, and a set timer must be ≥ 50 ms.</summary>
/// <remarks>
/// The trigger and 50 ms rules are <b>DELIBERATELY STRICTER THAN THE RUNTIME</b>, which serves a
/// trigger-less tag (it simply never computes) and honours a 1 ms cadence. The Gitea #554 survey
/// trigger-less tag (it simply never computes) and honours a 1 ms cadence. The tag-config survey
/// re-confirmed both and left them alone — they are documented on
/// <c>CalculationTagDefinitionFactory</c> as the reason its deploy gate must NOT restate them, since a
/// deploy warning can be promoted to a blocking error against a config the driver serves. The parse
@@ -86,7 +86,7 @@ public sealed class CalculationTagConfigModel
return "Timer interval must be at least 50 ms.";
}
// Gitea #554 backstop — expected silent for Calculation, whose reader refuses only a blob with no
// Backstop — expected silent for Calculation, whose reader refuses only a blob with no
// usable 'scriptId'. ⚠️ It gates on the PARSE VERDICT: this driver's Inspect emits advisories for
// blobs the reader ACCEPTS (a non-boolean 'changeTriggered', a discarded 'timerIntervalMs'), so a
// non-empty-inspection gate would refuse configs the runtime serves.
@@ -41,7 +41,7 @@ public sealed record CsvTypedColumn(
/// A column that writes <c>dataType</c> while the driver prefers a <c>driverDataType</c> alias does
/// not actually control the tag's type: the alias, carried through in the free-form
/// <c>TagConfigJson</c> cell, out-ranks it at the driver, so an operator's edit of the typed column
/// is accepted and then silently ignored (Gitea #553). Knowing the whole set is what lets the
/// is accepted and then silently ignored. Knowing the whole set is what lets the
/// export residual drop the alias, the export cell show the <i>effective</i> value, and a firing
/// column clear the alias so it genuinely wins.
/// </para>
@@ -51,7 +51,7 @@ public sealed record CsvTypedColumn(
/// <summary>
/// Per-driver mapping between a CSV row's <b>typed</b> columns and a tag's driver-specific
/// <c>TagConfig</c> JSON. The map is the inverse pair the WP5 CSV import/export path pivots on:
/// <c>TagConfig</c> JSON. The map is the inverse pair the CSV import/export path pivots on:
/// <see cref="ApplyTypedColumns"/> folds a row's typed columns onto a base TagConfig (typed column wins
/// on conflict); <see cref="ReadTypedColumns"/> projects a stored TagConfig back to its typed cells for
/// export. Lives next to the <c><![CDATA[<Driver>TagConfigModel]]></c> types so model + map evolve
@@ -74,14 +74,14 @@ public abstract class CsvDriverTagMap
/// <summary>The root TagConfig JSON keys this map owns (used to compute the export residual) — every
/// <see cref="CsvTypedColumn.OwnedJsonKeys"/> entry, aliases included, so the residual can never carry a
/// spelling that out-ranks the typed column beside it (Gitea #553).</summary>
/// spelling that out-ranks the typed column beside it.</summary>
public IReadOnlyList<string> JsonKeys => Columns.SelectMany(c => c.OwnedJsonKeys).Distinct(StringComparer.Ordinal).ToArray();
/// <summary>
/// Applies one typed column's already-parsed effect to <paramref name="target"/>: removes every
/// <b>other</b> spelling the runtime would read for that column, so the value the column supplied is
/// the one the driver actually sees. Callers write the column's own <see cref="CsvTypedColumn.JsonKey"/>
/// themselves (model-backed maps do it through the model). Gitea #553.
/// themselves (model-backed maps do it through the model).
/// </summary>
/// <param name="target">The merged TagConfig object being assembled.</param>
/// <param name="column">The typed column that supplied a value on this row.</param>
@@ -100,7 +100,7 @@ public abstract class CsvDriverTagMap
/// Reads one typed column's <b>effective</b> cell value out of a stored TagConfig for export: the
/// first non-blank string under <see cref="CsvTypedColumn.OwnedJsonKeys"/>, in the runtime's own
/// precedence. Exporting the canonical key alone would print the spelling the driver is <i>ignoring</i>
/// and leave the winning alias in the residual, which is how the re-import trap in Gitea #553 got set.
/// and leave the winning alias in the residual, which is how the re-import trap got set.
/// </summary>
/// <param name="source">The stored TagConfig object.</param>
/// <param name="column">The typed column to project.</param>
@@ -190,29 +190,25 @@ public sealed class ModelBackedCsvDriverTagMap<TModel> : CsvDriverTagMap
public override IReadOnlyList<CsvTypedColumn> Columns { get; }
/// <inheritdoc/>
/// <remarks>
/// <b>The base cell's own tokens are restored verbatim over the model's serialisation (Gitea #553).</b>
/// The model round-trip is what merges the typed columns and stamps a default for a key the row
/// declares nowhere — but <c>FromJson</c> is deliberately lenient (it has to LOAD a poisoned blob so an
/// operator can fix it), so a <c>"dataType":"Intt16"</c> the row carried in its free-form
/// <c>TagConfigJson</c> cell came back out of <c>ToJson</c> as the model's <i>default</i> — the
/// operator's typo replaced by a valid-looking value before the import gate, or any later gate, could
/// ever see it. Only keys the model does not own survived to be judged.
/// <para>
/// So every key the base cell actually carried is written back afterwards, unless a non-blank
/// typed column overrode it. Nothing here decides whether a token is <i>good</i>: that stays with
/// <see cref="TagConfigValidator"/> on the assembled blob (and with
/// <c>IRawTreeService.ImportTagsAsync</c> behind it), which asks each driver model's own
/// <c>Validate()</c> — one authority. This method's only job is to stop destroying the evidence
/// before that authority is consulted.
/// </para>
/// <para>
/// A key a non-blank column DID override is <b>not</b> restored, and its out-ranking aliases are
/// cleared: the typed column winning over a conflicting cell key is this map's documented contract,
/// the review grid reports each such override by name, and refusing the row instead would leave an
/// operator no way to repair a poisoned cell through the very columns that exist for it.
/// </para>
/// </remarks>
// The base cell's own tokens are restored verbatim over the model's serialisation.
// The model round-trip is what merges the typed columns and stamps a default for a key the row
// declares nowhere — but FromJson is deliberately lenient (it has to LOAD a poisoned blob so an
// operator can fix it), so a "dataType":"Intt16" the row carried in its free-form
// TagConfigJson cell came back out of ToJson as the model's default — the
// operator's typo replaced by a valid-looking value before the import gate, or any later gate, could
// ever see it. Only keys the model does not own survived to be judged.
//
// So every key the base cell actually carried is written back afterwards, unless a non-blank
// typed column overrode it. Nothing here decides whether a token is good: that stays with
// TagConfigValidator on the assembled blob (and with
// IRawTreeService.ImportTagsAsync behind it), which asks each driver model's own
// Validate() — one authority. This method's only job is to stop destroying the evidence
// before that authority is consulted.
//
// A key a non-blank column DID override is not restored, and its out-ranking aliases are
// cleared: the typed column winning over a conflicting cell key is this map's documented contract,
// the review grid reports each such override by name, and refusing the row instead would leave an
// operator no way to repair a poisoned cell through the very columns that exist for it.
public override string ApplyTypedColumns(string? baseJson, IReadOnlyDictionary<string, string> row)
{
var baseObj = TagConfigJson.ParseOrNew(baseJson);
@@ -324,7 +320,7 @@ public sealed class RawKeyCsvDriverTagMap : CsvDriverTagMap
};
// Without this the cell's alias survives beside the key just written and OUT-RANKS it at the
// driver, so the operator's column edit is accepted and then ignored (Gitea #553).
// driver, so the operator's column edit is accepted and then ignored.
ClearOutrankingAliases(o, col.Meta);
}
}
@@ -400,7 +396,7 @@ public static class CsvValues
}
/// <summary>
/// Registry of the WP5 CSV column dictionary: the common columns every device's export/import carries,
/// Registry of the CSV column dictionary: the common columns every device's export/import carries,
/// plus the per-driver typed <see cref="CsvDriverTagMap"/> resolved by driver type. The single authority
/// for "which columns does a device of driver X have".
/// </summary>
@@ -433,7 +429,7 @@ public static class CsvColumnMap
/// <summary>The Calculation (virtual-tag) driver-type string.</summary>
/// <remarks>Retained as an alias for <see cref="DriverTypeNames.Calculation"/>, which now exists — the
/// original note here ("not yet a DriverTypeNames constant; its factory lands in a later Batch-2
/// original note here ("not yet a DriverTypeNames constant; its factory lands in a later
/// package") went stale once the factory registered.</remarks>
public const string CalculationDriverType = DriverTypeNames.Calculation;
@@ -595,7 +591,7 @@ public static class CsvColumnMap
// MTConnect is the one driver whose blob accepts several spellings per field, so its two identity
// columns declare the runtime's whole read precedence rather than just the key they write —
// mirroring MTConnectTagDefinitionFactory.TryFromTagConfig's FirstNonBlank(...) pairs, and the
// MTConnectTagConfigModel load that already mirrors them for the editor (Gitea #550/#553).
// MTConnectTagConfigModel load that already mirrors them for the editor.
new RawKeyCsvDriverTagMap(DriverTypeNames.MTConnect, new[]
{
new CsvRawKeyColumn(
@@ -20,7 +20,7 @@ public sealed class FocasTagConfigModel
private JsonObject _bag = new();
// The blob this model was LOADED FROM, or null when built by object initialiser — the input to the
// Gitea #554 parse consult (see TagConfigParseGate).
// Parse consult (see TagConfigParseGate).
private string? _source;
/// <summary>Loads a model from a TagConfig JSON string, defaulting any absent field and retaining
@@ -54,14 +54,14 @@ public sealed class FocasTagConfigModel
/// <summary>Validation hook; returns an error message or null when the model is valid.</summary>
/// <returns>An error message describing the validation failure, or null when the model is valid.</returns>
/// <remarks>
/// <b>This runs the driver's real parser, not a non-empty check</b> (Gitea #540). It used to
/// <b>This runs the driver's real parser, not a non-empty check</b>. It used to
/// accept any non-blank string, which is how 20 tags carrying a browse full reference
/// (<c>10.201.31.5:8193/Identity/SeriesNumber</c>) were authored, deployed and sealed green —
/// the driver then skipped every one at init and they read <c>BadNodeIdUnknown</c> forever
/// with no signal anywhere. An address that cannot be parsed cannot be polled, so the
/// rejection belongs here, where the operator is still looking at the field.
/// <para><see cref="FocasAddress"/> lives in the driver's <c>Contracts</c> assembly precisely
/// so this project can call it without referencing the runtime driver (Gitea #526).</para>
/// so this project can call it without referencing the runtime driver.</para>
/// </remarks>
public string? Validate()
{
@@ -69,18 +69,18 @@ public sealed class FocasTagConfigModel
// TryReadEnumStrict, so a present-but-invalid string rejects the whole tag at the driver
// (BadNodeIdUnknown) while the lenient load above defaults it to Int32. Accepting it here would
// let the CSV-import and API paths — which save the blob verbatim — deploy an unreadable tag,
// the same shape as the #540 address gap this method already closes (Gitea #549).
// the same shape as the address gap this method already closes.
if (TagConfigJson.DescribeInvalidEnum<FocasDataType>(_bag, "dataType") is { } dtError) return dtError;
if (string.IsNullOrWhiteSpace(Address)) return "Address is required.";
// DELIBERATELY STRICTER THAN THE RUNTIME (Gitea #540), and the #554 survey re-confirmed it: the
// DELIBERATELY STRICTER THAN THE RUNTIME, and the parse-gate survey re-confirmed it: the
// reader ACCEPTS an unparseable address — FocasTagDefinitionFactory.Inspect only advises about it —
// and the driver then skips the tag at startup. That is the defect #540 closed, so this check stays
// and the driver then skips the tag at startup. That is the earlier defect closed, so this check stays
// ahead of the parse consult below and is never replaced by it.
if (FocasAddress.TryParse(Address) is null) return DescribeUnparseableAddress(Address);
// Gitea #554 backstop. ⚠️ It gates on the PARSE VERDICT, never on Inspect being non-empty: FOCAS's
// Parse-gate backstop. ⚠️ It gates on the PARSE VERDICT, never on Inspect being non-empty: FOCAS's
// inspector emits advisories for blobs the reader ACCEPTS (an unparseable address, an authored
// 'writable':true on a read-only wire), and promoting those to authoring errors would make the modal
// stricter than the runtime and leave rows nobody can save.
@@ -99,7 +99,7 @@ public sealed class FocasTagConfigModel
/// <param name="address">The rejected address.</param>
/// <returns>The message.</returns>
internal static string DescribeUnparseableAddress(string address) =>
// An ALARM: address gets its selector's own reason — the same text the deploy-time inspector gives (#647).
// An ALARM: address gets its selector's own reason — the same text the deploy-time inspector gives.
FocasAddress.DescribeAlarmAddressError(address) is { } alarmError
? $"'{address.Trim()}' is not a valid FOCAS alarm address: {alarmError}."
: $"'{address.Trim()}' is not a FOCAS address. Expected a PMC address (X0.0, R100, F20.3), " +
@@ -13,7 +13,7 @@ namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns.TagEditors;
/// <para>
/// <see cref="MtCategory"/>/<see cref="MtType"/>/<see cref="MtSubType"/>/<see cref="Units"/> come
/// from the Agent's <c>/probe</c> response (see <c>MTConnectTagDefinition</c> in the driver's
/// Contracts project) and are shown read-only by Task 18's editor — this model still round-trips
/// Contracts project) and are shown read-only by the editor — this model still round-trips
/// them so a browse-commit that stamped them survives a manual edit of <see cref="DataType"/>.
/// <see cref="MtDevice"/>/<see cref="MtComponent"/> are pure author context (which physical
/// device/component this DataItem belongs to); nothing downstream consumes them.
@@ -66,7 +66,7 @@ public sealed class MTConnectTagConfigModel
// Enum.TryParse falls back to String on ANY unrecognised value, so without this a misspelled name
// ("Strng") or a quoted number ("8" -> Float64, the ParseEnum numeric-text trap) loads as a
// *valid-looking* enum value with no signal that it is not what the operator wrote — while the strict
// runtime rejects the tag outright (Gitea #549). Captured as the raw TOKEN, not via GetString: the
// runtime rejects the tag outright. Captured as the raw TOKEN, not via GetString: the
// runtime deserialises both spellings into `string?` DTO fields, so a NON-string token
// (`"dataType": 8`, `"driverDataType": 8`) throws JsonException there and rejects the tag too, where
// GetString would report it as simply absent. ToJson() always re-writes dataType as a name and drops
@@ -80,7 +80,7 @@ public sealed class MTConnectTagConfigModel
private string _rawDataTypeKey = CanonicalDataTypeKey;
// The blob this model was LOADED FROM, or null when built by object initialiser — the input to the
// Gitea #554 parse consult (see TagConfigParseGate). Same capture-the-source pattern as _rawDataType.
// Parse consult (see TagConfigParseGate). Same capture-the-source pattern as _rawDataType.
private string? _source;
private JsonObject _bag = new();
@@ -104,9 +104,9 @@ public sealed class MTConnectTagConfigModel
/// <c>tags[]</c> field name, and the spelling a hand-authored or driver-shaped blob carries) wins
/// over <c>dataType</c> (this model's canonical key).
/// <para>
/// Reading only <c>dataType</c> was Gitea <b>#550</b>, and it broke in both directions at once: a
/// Reading only <c>dataType</c> was a defect, and it broke in both directions at once: a
/// blob carrying <c>"driverDataType": "Strng"</c> sailed through authoring while the runtime
/// rejected the tag (the residual slice of #549), and — worse — a VALID <c>driverDataType</c>
/// rejected the tag, and — worse — a VALID <c>driverDataType</c>
/// silently overrode whatever type this editor displayed and saved, so the editor showed a lie.
/// </para>
/// <para>
@@ -159,7 +159,7 @@ public sealed class MTConnectTagConfigModel
{
// Normalise onto the canonical key: a blob loaded via an alias must not keep the alias, or the
// two spellings drift on the next edit and the driver silently reads the stale one. This holds
// for the coercion type (driverDataType, Gitea #550) exactly as it does for the id spellings —
// for the coercion type (driverDataType) exactly as it does for the id spellings —
// and because driverDataType OUT-RANKS dataType at the driver, leaving it behind would mean the
// type the operator just picked never reached the runtime at all.
TagConfigJson.Set(_bag, "dataItemId", null);
@@ -185,7 +185,7 @@ public sealed class MTConnectTagConfigModel
/// The <c>dataType</c> rule is not stated here — it is asked of
/// <see cref="MTConnectTagDefinitionFactory.IsAcceptedDataTypeName"/>, the same predicate the driver
/// and the deploy gate use. One authority, so this gate can never end up weaker than the runtime
/// again (Gitea #549). Note that the previous, digits-only check is NOT retained as a tailored
/// again. Note that the previous, digits-only check is NOT retained as a tailored
/// special case: the runtime draws no distinction between a bare number and a misspelled name —
/// both fail that one predicate and both draw the same <c>Inspect</c> warning — so a second message
/// here would be a second statement of a rule this model does not own.
@@ -206,7 +206,7 @@ public sealed class MTConnectTagConfigModel
+ $"data type. Valid: {string.Join(", ", Enum.GetNames<DriverDataType>())}.";
}
// Gitea #554 backstop — expected silent for MTConnect, whose reader refuses only an unparseable
// Backstop — expected silent for MTConnect, whose reader refuses only an unparseable
// document, a JSON null, an id under none of the three spellings, and an unreadable coercion type,
// all covered above. It is here so a future reader rule cannot become a gap.
return TagConfigParseGate.Describe(
@@ -217,7 +217,7 @@ public sealed class MTConnectTagConfigModel
}
/// <summary>
/// Advisory warnings (#613) — NEVER an error and never routed through <see cref="Validate"/>: the
/// Advisory warnings — NEVER an error and never routed through <see cref="Validate"/>: the
/// deploy gate does not refuse these, so authoring must not either ("never stricter than the gate").
/// One rule: the declared <see cref="DataType"/> cannot hold the type
/// <see cref="MTConnectDataTypeInference.Infer"/> derives from the stamped
@@ -234,7 +234,7 @@ public sealed class MTConnectTagConfigModel
/// <returns>Zero or more human-readable warnings.</returns>
public IReadOnlyList<string> Warnings()
{
// #627: an array (TIME_SERIES) tag is served as double[] only. Independent of the probe metadata —
// An array (TIME_SERIES) tag is served as double[] only. Independent of the probe metadata —
// the array flag is authored on the tag, and any other declared element type reads BadNotSupported.
var arrayWarning = _bag.TryGetPropertyValue("isArray", out var arr)
&& arr is JsonValue av && av.TryGetValue<bool>(out var isArray) && isArray
@@ -25,7 +25,7 @@ public sealed class ModbusTagConfigModel
/// <summary>String length in characters for String tags.</summary>
public int StringLength { get; set; }
/// <summary>Optional writable flag (R2-11). <c>null</c> ⇒ the key is omitted (driver default true);
/// <summary>Optional writable flag. <c>null</c> ⇒ the key is omitted (driver default true);
/// an explicit <c>false</c> makes the equipment tag read-only. Preserved across load→save so an absent
/// key stays absent.</summary>
public bool? Writable { get; set; }
@@ -80,10 +80,10 @@ public sealed class ModbusTagConfigModel
/// 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>/
/// <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>
/// blob verbatim — deploy a tag the driver skips. 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
/// <c>stringByteOrder</c> is the fourth: 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
@@ -92,7 +92,7 @@ public sealed class ModbusTagConfigModel
/// </para>
/// <para>
/// <b>Everything the mapper refuses for a NON-enum reason is covered by the parse consult</b>
/// (Gitea #554), not by rules restated here: an absent <c>region</c>, an absent or non-numeric or
/// not by rules restated here: an absent <c>region</c>, an absent or non-numeric or
/// out-of-0–65535 <c>address</c>, a <c>String</c> tag with no <c>stringLength</c>, a
/// <c>BitInRegister</c> tag whose <c>bitIndex</c> narrows above 15. Modbus was the one editor with
/// no required field at all, so <c>{}</c> — what the modal persists for a tag whose config was
@@ -84,7 +84,7 @@ public sealed class MqttTagConfigModel
public string Topic { get; set; } = "";
/// <summary>
/// The topic a write PUBLISHES to (Plain mode), or blank when the tag is read-only (Gitea #508).
/// The topic a write PUBLISHES to (Plain mode), or blank when the tag is read-only.
/// Deliberately distinct from <see cref="Topic"/> — a tag legitimately reads <c>.../state</c> and
/// writes <c>.../set</c> — and blank is meaningful: the driver refuses the write with
/// <c>BadNotWritable</c> rather than publishing nowhere. Unused in Sparkplug mode, where a
@@ -165,7 +165,7 @@ public sealed class MqttTagConfigModel
private JsonObject _bag = new();
// The blob this model was LOADED FROM, or null when built by object initialiser — the input to the
// Gitea #554 parse consult (see TagConfigParseGate).
// parse consult (see TagConfigParseGate).
private string? _source;
/// <summary>
@@ -223,7 +223,7 @@ public sealed class MqttTagConfigModel
/// (<see cref="DataType"/> for Plain — always present; <see cref="MetricDataType"/> for
/// Sparkplug — omitted unless the operator set an override): which field wins is decided by
/// <see cref="Mode"/> at write time. <c>payloadFormat</c> is the one key written for <b>Plain
/// only</b> (Gitea #513) — see its line below for why it alone needs the mode test. Every other
/// only</b> — see its line below for why it alone needs the mode test. Every other
/// key is unconditional: mode-inapplicable keys (e.g. <c>topic</c> while Sparkplug, or
/// <c>groupId</c> while Plain) are written/cleared exactly as their typed field says, and because
/// each of those fields is blank-⇒-omit, an absent key stays absent while a retyped tag's real
@@ -241,7 +241,7 @@ public sealed class MqttTagConfigModel
// shape dropdown would lose authored configuration rather than merely tidy the blob.
TagConfigJson.Set(_bag, WriteTopicKey, string.IsNullOrWhiteSpace(WriteTopic) ? null : WriteTopic.Trim());
// Plain-only (Gitea #513). Unlike every other Plain key here, PayloadFormat is a NON-NULLABLE
// Plain-only. Unlike every other Plain key here, PayloadFormat is a NON-NULLABLE
// typed field, so an unconditional write does not merely preserve a retyped tag's leftover — it
// INVENTS "payloadFormat":"Json" in the blob of a Sparkplug tag that never had one. The key names
// a decode path that Sparkplug does not use (MqttTagDefinitionFactory routes on the descriptor
@@ -314,7 +314,7 @@ public sealed class MqttTagConfigModel
var error = Mode == MqttMode.SparkplugB ? ValidateSparkplug() : ValidatePlain();
if (error is not null) { return error; }
// Gitea #554 backstop, gating on the PARSE VERDICT (never on Inspect being non-empty — the MQTT
// Parse-consult backstop, gating on the PARSE VERDICT (never on Inspect being non-empty — the MQTT
// inspector advises about a wildcard topic on blobs the reader ACCEPTS). The verdict is the UNION of
// the two readers, matching MqttTagDefinitionFactory.Inspect's own accept gate: a blob is served if
// EITHER shape reads it, and this model's Mode is only an inference from the descriptor keys.
@@ -437,8 +437,8 @@ public sealed class MqttTagConfigModel
/// driver would happily default. The VERDICT is the runtime's own
/// <see cref="RuntimeTagConfigJson.ClassifyEnumText{TEnum}"/>, never a local
/// <see cref="Enum.TryParse{TEnum}(string, bool, out TEnum)"/>: a numeric spelling such as
/// <c>"1"</c> parses there and names no member (Driver.Sql.Contracts-002), so restating the rule
/// here would accept a blob the driver refuses — the Gitea #549 direction.
/// <c>"1"</c> parses there and names no member, so restating the rule
/// here would accept a blob the driver refuses — the same direction.
/// </summary>
/// <typeparam name="TEnum">The enum type expected.</typeparam>
/// <param name="o">The TagConfig key bag.</param>
@@ -92,7 +92,7 @@ public sealed class NativeAlarmModel
}
else
{
// Toggled off (#642): the alarm object must go, or a "disabled" tag would still deploy as a condition.
// Toggled off: the alarm object must go, or a "disabled" tag would still deploy as a condition.
_root.Remove("alarm");
}
@@ -36,10 +36,10 @@ public sealed class OpcUaClientTagConfigModel
/// or present-but-non-string <c>nodeId</c> beside a perfectly good legacy <c>NodeId</c> is a
/// REJECTED blob, not a fallback. Copying <c>MTConnectTagConfigModel</c>'s <c>FirstNonBlank</c>
/// walk here would make this editor accept a blob the driver skips — the absolute direction
/// Gitea #554 forbids.
/// the parse consult forbids.
/// </para>
/// <para>
/// Reading only <c>nodeId</c> was Gitea <b>#557</b> item 1: a legacy blob was SERVED by the driver
/// Reading only <c>nodeId</c> was a defect: a legacy blob was SERVED by the driver
/// yet opened with an empty reference field and could not be saved untouched, so the editor was
/// stricter than the reader — authoring blocking config the runtime honours.
/// <see cref="ToJson"/> therefore normalises onto <see cref="NodeIdKey"/> and DROPS the legacy
@@ -59,7 +59,7 @@ public sealed class OpcUaClientTagConfigModel
private JsonObject _bag = new();
// The blob this model was LOADED FROM, or null when built by object initialiser — the input to the
// Gitea #554 parse consult (see TagConfigParseGate).
// parse consult (see TagConfigParseGate).
private string? _source;
/// <summary>Loads a model from a TagConfig JSON string, defaulting any absent field and retaining
@@ -100,8 +100,8 @@ public sealed class OpcUaClientTagConfigModel
/// <summary>Validation hook; returns an error message or null when the model is valid.</summary>
/// <remarks>
/// The Gitea #554 parse consult is a backstop here, and the required-reference check above is now
/// exactly as precedence-aware as the reader (Gitea #557 item 1): <see cref="ReadNodeId"/> yields
/// The parse consult is a backstop here, and the required-reference check above is now
/// exactly as precedence-aware as the reader: <see cref="ReadNodeId"/> yields
/// the very token <see cref="OpcUaClientTagDefinitionFactory.TryReadNodeId"/> would consult — blank
/// for every shape it refuses, non-blank for every shape it serves — so the fast path agrees with
/// the parse verdict on the whole rejection surface rather than under-reading one spelling of it.
@@ -16,7 +16,7 @@ public sealed class S7TagConfigModel
/// <summary>For <c>DataType = String</c>: S7-string max length (max 254).</summary>
public int StringLength { get; set; }
/// <summary>Optional writable flag (R2-11); <c>null</c> ⇒ omitted (driver default true), explicit
/// <summary>Optional writable flag; <c>null</c> ⇒ omitted (driver default true), explicit
/// <c>false</c> ⇒ read-only. Preserved across load→save.</summary>
public bool? Writable { get; set; }
@@ -26,7 +26,7 @@ public sealed class S7TagConfigModel
// 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.
// 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
@@ -36,7 +36,7 @@ public sealed class S7TagConfigModel
private bool _dataTypeMissingInSource;
// The blob this model was LOADED FROM, or null when built by object initialiser — the parse consult's
// input (Gitea #554). Same capture-the-source reasoning as _dataTypeMissingInSource above.
// input. Same capture-the-source reasoning as _dataTypeMissingInSource above.
private string? _source;
/// <summary>Loads a model from a TagConfig JSON string, defaulting any absent field and retaining
@@ -78,9 +78,9 @@ public sealed class S7TagConfigModel
/// <see cref="DataType"/>: <c>S7TagDefinitionFactory</c> reads it 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>Int16</c>. Accepting it here would let the CSV-import
/// and API paths — which save the blob verbatim — deploy an unreadable tag (Gitea #549).
/// and API paths — which save the blob verbatim — deploy an unreadable tag.
/// <para>
/// <b>An ABSENT <c>dataType</c> is rejected too (Gitea #551), and S7 is the only driver where
/// <b>An ABSENT <c>dataType</c> is rejected too, 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.
@@ -112,7 +112,7 @@ public sealed class S7TagConfigModel
+ string.Join(", ", Enum.GetNames<S7DataType>()) + ".";
}
// S7-016: array shape is judged against the driver's INIT guards, which THROW (failing the whole
// Array shape is judged against the driver's INIT guards, which THROW (failing the whole
// driver's init, not just this tag) for a wide-type array and for a writable Bool array. The
// isArray / arrayLength keys themselves belong to the TagModal's generic array controls
// (TagArrayConfig) and are intentionally not fields of this model, so read them off the key bag.
@@ -134,7 +134,7 @@ public sealed class S7TagConfigModel
}
}
// Gitea #554: the reader's remaining, non-enum refusal — a String tag whose 'stringLength' is
// the reader's remaining, non-enum refusal — a String tag whose 'stringLength' is
// negative or above 254 (S7 REJECTS it rather than clamping) — is not restated here. The verdict and
// the wording both come from the driver's own reader, via TagConfigParseGate.
return TagConfigParseGate.Describe(
@@ -54,7 +54,7 @@ public sealed class SqlTagConfigModel
private string? _invalidTypeRaw;
// The blob this model was LOADED FROM, or null when built by object initialiser — the input to the
// Gitea #554 parse consult (see TagConfigParseGate).
// parse consult (see TagConfigParseGate).
private string? _source;
/// <summary>Loads a model from a TagConfig JSON string, defaulting any absent field and retaining every
@@ -146,7 +146,7 @@ public sealed class SqlTagConfigModel
return "model is not a supported Sql tag model.";
}
// Gitea #554: the parser's RECOGNITION check is the rule nothing above states, and it is the one Sql
// The parser's RECOGNITION check is the rule nothing above states, and it is the one Sql
// rejection an otherwise-complete blob can hit — TryParse refuses a config that carries neither a
// 'model' key nor "driver":"Sql", because it cannot tell a Sql tag from any other driver's blob. The
// editor always writes 'model' on save, so this only ever fires for a hand-authored / CSV / API blob.
@@ -161,7 +161,7 @@ public sealed class SqlTagConfigModel
// non-string ⇒ (null, null) — nothing to validate; a present string that parses ⇒ (value, null); a
// present string that does NOT parse ⇒ (null, offendingString) so Validate can reject it. The verdict is
// the RUNTIME's own ClassifyEnumText, not a local Enum.TryParse — restating it is how the two doors drift
// (Gitea #549), and a numeric spelling like "1" is exactly where they would have (Driver.Sql.Contracts-002).
// and a numeric spelling like "1" is exactly where they would have.
private static (TEnum? value, string? invalidRaw) ReadEnumStrict<TEnum>(JsonObject o, string name)
where TEnum : struct, Enum
{
@@ -99,9 +99,9 @@ public static class TagConfigJson
/// <para>
/// <see cref="GetEnum{TEnum}"/> is deliberately lenient — it must be, because a model has to
/// LOAD a poisoned blob to let an operator fix it — but leniency at the save gate is the
/// Gitea #549 defect: every driver's runtime read is
/// defect: every driver's runtime read is
/// <c>TagConfigJson.TryReadEnumStrict</c>, which REJECTS the whole tag on a present-but-invalid
/// string (R2-11 Phase C), so a typo the modal accepts and rewrites is a tag the driver would
/// string, so a typo the modal accepts and rewrites is a tag the driver would
/// have skipped with <c>BadNodeIdUnknown</c> on the CSV-import and API paths, which save the
/// blob verbatim. A model's <c>Validate()</c> therefore calls this on its ORIGINAL key bag.
/// </para>
@@ -1,18 +1,18 @@
namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns.TagEditors;
/// <summary>
/// The non-enum half of the authoring gate (Gitea #554): a driver's <c>&lt;Driver&gt;TagConfigModel.Validate()</c>
/// The non-enum half of the authoring gate: a driver's <c>&lt;Driver&gt;TagConfigModel.Validate()</c>
/// asks that driver's own runtime parse whether it would read the blob, and refuses the save when it
/// would not. One authority for the VERDICT and for the WORDING — the same shape #551 gave the deploy
/// would not. One authority for the VERDICT and for the WORDING — the same shape the deploy
/// gate, pointed at the other end of the pipe.
/// <para>
/// <b>Why the models could not simply grow more rules.</b> Before this, <c>Validate()</c> judged the
/// enum keys (against the runtime's own <c>DescribeInvalidEnumText</c>, Gitea #549/#551) plus a few
/// enum keys (against the runtime's own <c>DescribeInvalidEnumText</c>) plus a few
/// hand-written required-field checks, and nothing else. Every remaining reason a driver's reader
/// refuses a tag — an absent <c>region</c>, an <c>"address":"notanumber"</c>, an S7
/// <c>stringLength</c> of 300, a TwinCAT <c>dataType:"Structure"</c> — met no gate until deploy, or
/// until the driver skipped the tag. Re-stating each of those in each model would have been N more
/// hand-mirrored rules to drift, which is exactly the defect #551 closed on the deploy side.
/// hand-mirrored rules to drift, which is exactly the defect already closed on the deploy side.
/// </para>
/// </summary>
/// <remarks>
@@ -22,7 +22,7 @@ namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns.TagEditors;
/// will be skipped and that <c>writable:true</c> cannot write, MQTT warns about a wildcard topic,
/// Calculation warns about a discarded <c>timerIntervalMs</c>. Treating a non-empty inspection as an
/// authoring error would make the modal STRICTER than the runtime and leave rows nobody can save —
/// the #520/#535 trap. So <see cref="Describe"/> calls the inspector only once the parse has already
/// the same trap as an over-strict gate. So <see cref="Describe"/> calls the inspector only once the parse has already
/// refused, purely to word the refusal.
/// </para>
/// <para>
@@ -16,14 +16,14 @@ public sealed class TwinCATTagConfigModel
/// <summary>TwinCAT / IEC 61131-3 atomic data type.</summary>
public TwinCATDataType DataType { get; set; } = TwinCATDataType.DInt;
/// <summary>Optional writable flag (R2-11); <c>null</c> ⇒ omitted (driver default true), explicit
/// <summary>Optional writable flag; <c>null</c> ⇒ omitted (driver default true), explicit
/// <c>false</c> ⇒ read-only. Preserved across load→save.</summary>
public bool? Writable { get; set; }
private JsonObject _bag = new();
// The blob this model was LOADED FROM, or null when built by object initialiser — the input to the
// Gitea #554 parse consult (see TagConfigParseGate).
// parse consult (see TagConfigParseGate).
private string? _source;
/// <summary>Loads a model from a TagConfig JSON string, defaulting any absent field and retaining
@@ -64,10 +64,10 @@ public sealed class TwinCATTagConfigModel
/// <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>DInt</c>. Accepting it here
/// would let the CSV-import and API paths — which save the blob verbatim — deploy an unreadable
/// tag (Gitea #549).
/// tag.
/// <para>
/// <b><c>dataType: "Structure"</c> is the reason this model needed more than an enum check</b>
/// (Gitea #554): it is a perfectly valid <see cref="TwinCATDataType"/> NAME, so every spelling
/// <b><c>dataType: "Structure"</c> is the reason this model needed more than an enum check</b>:
/// it is a perfectly valid <see cref="TwinCATDataType"/> NAME, so every spelling
/// gate passes it, and the reader refuses it anyway — the driver does not serve UDT / FB-instance
/// tags. The rule is not restated here; the parse consult asks the reader and quotes its answer.
/// </para>
@@ -23,8 +23,8 @@ public sealed class UnsTreeService(
IDbContextFactory<OtOpcUaConfigDbContext> dbFactory,
IEffectiveNameGuard? guard = null) : IUnsTreeService
{
// The v3 Batch-3 effective-name uniqueness guard (references / VirtualTags / ScriptedAlarms share the
// equipment's UNS NodeId space). WP2 registers the real implementation; production DI always injects it.
// The effective-name uniqueness guard (references / VirtualTags / ScriptedAlarms share the
// equipment's UNS NodeId space). Production DI always injects it.
// A null (unregistered) guard falls back to a no-op — collisions are then caught only at the deploy
// gate — which also lets unit tests that don't exercise the guard construct the service with just a
// db factory. Tests that DO exercise the guard pass a fake.
@@ -471,12 +471,13 @@ public sealed class UnsTreeService(
/// <summary>
/// A no-op <see cref="IEffectiveNameGuard"/> used only when no guard was injected (unit tests that do
/// not exercise the guard; a mis-wired DI). It always reports "free" — the deploy gate remains the
/// backstop. Production always injects the real WP2 guard.
/// backstop. Production always injects the real guard.
/// </summary>
private sealed class NoOpEffectiveNameGuard : IEffectiveNameGuard
{
public static readonly NoOpEffectiveNameGuard Instance = new();
/// <inheritdoc />
public Task<string?> CheckAsync(
string equipmentId, string proposedEffectiveName, EffectiveNameSourceKind kind,
string? excludeSourceId, CancellationToken ct = default) => Task.FromResult<string?>(null);
@@ -842,7 +843,7 @@ public sealed class UnsTreeService(
}
// v3: equipment no longer binds a driver — the reference-only Tags tab points at raw tags — so
// the old decision-#122 driver-cluster guard is gone.
// the old driver-cluster guard is gone.
var uuid = Guid.NewGuid();
var equipmentId = $"EQ-{uuid.ToString("N")[..12]}";
@@ -908,7 +909,7 @@ public sealed class UnsTreeService(
// An error rather than a skip: a skipped row is one the operator already has, while this is
// one they meant to add and cannot. Left unchecked it would import and then block the next
// deployment — fleet-wide, since a deployment snapshots the whole database (Gitea #535).
// deployment — fleet-wide, since a deployment snapshots the whole database.
if (!UnsSegment.IsValid(row.Name))
{
errors.Add($"Row '{row.MachineCode}': {UnsSegment.Describe("equipment name", row.Name)}.");
@@ -974,7 +975,7 @@ public sealed class UnsTreeService(
return new UnsMutationResult(false, $"MachineCode '{input.MachineCode}' already exists in this fleet.");
}
// v3: equipment no longer binds a driver — no decision-#122 driver-cluster guard.
// v3: equipment no longer binds a driver — no driver-cluster guard.
// Equipment↔driver binding retired in v3 — no DriverInstanceId column remains.
entity.UnsLineId = input.UnsLineId;
@@ -1258,7 +1259,7 @@ public sealed class UnsTreeService(
}
/// <summary>
/// v3 (M1): when the bound script uses <c>{{equip}}/&lt;RefName&gt;</c>, every <c>&lt;RefName&gt;</c> must
/// v3: when the bound script uses <c>{{equip}}/&lt;RefName&gt;</c>, every <c>&lt;RefName&gt;</c> must
/// resolve to one of the owning equipment's <c>UnsTagReference</c> effective names (its
/// <c>DisplayNameOverride</c> else the backing raw tag's <c>Name</c>) — the same set the compose seams
/// substitute against and the deploy gate (<c>DraftValidator.ValidateEquipReferenceResolution</c>)
@@ -1683,7 +1684,7 @@ public sealed class UnsTreeService(
var nameGuard = await _guard.CheckAsync(equipmentId, input.Name, EffectiveNameSourceKind.ScriptedAlarm, null, ct);
if (nameGuard is not null) return new UnsMutationResult(false, nameGuard);
// v3 Batch 3 (WP4): {{equip}}/<RefName> in the predicate script or message template must resolve.
// v3: {{equip}}/<RefName> in the predicate script or message template must resolve.
var equipGuard = await ValidateEquipTokenForAlarmAsync(db, equipmentId, input.PredicateScriptId, input.MessageTemplate, ct);
if (equipGuard is not null) return equipGuard.Value;
@@ -1721,7 +1722,7 @@ public sealed class UnsTreeService(
var nameGuard = await _guard.CheckAsync(entity.EquipmentId, input.Name, EffectiveNameSourceKind.ScriptedAlarm, scriptedAlarmId, ct);
if (nameGuard is not null) return new UnsMutationResult(false, nameGuard);
// v3 Batch 3 (WP4): {{equip}}/<RefName> in the predicate script or message template must resolve.
// v3: {{equip}}/<RefName> in the predicate script or message template must resolve.
var equipGuard = await ValidateEquipTokenForAlarmAsync(db, entity.EquipmentId, input.PredicateScriptId, input.MessageTemplate, ct);
if (equipGuard is not null) return equipGuard.Value;
@@ -1778,7 +1779,7 @@ public sealed class UnsTreeService(
/// The rejection for a UNS name that is not a usable path segment.
/// </summary>
/// <remarks>
/// ⚠️ <b>The service is where this is enforced, not the form (Gitea #535).</b> Before this, the
/// ⚠️ <b>The service is where this is enforced, not the form.</b> Before this, the
/// rule lived on the equipment form alone, so an area or line could be named "Packaging" or
/// "Line 1", save cleanly, and then fail the deploy — and because a deployment snapshots the
/// whole database, one bad name blocked <b>every</b> cluster's deploy, discovered by someone