docs(comments): correct 7 stale 'later task/milestone' comments (stillpending §9)

This commit is contained in:
Joseph Doherty
2026-06-15 09:47:08 -04:00
parent 68a0f759f0
commit b4af9e7f37
8 changed files with 31 additions and 26 deletions
@@ -4,9 +4,9 @@ namespace ZB.MOM.WW.OtOpcUa.Core.Scripting;
/// <summary>
/// Abstraction over the mechanism that publishes <see cref="ScriptLogEntry"/> records
/// to a downstream consumer (e.g. an Akka DPS <c>script-logs</c> topic). Implemented by
/// the concrete DPS publisher in a later task; the sink depends only on this interface
/// so the Core.Scripting layer has no Akka dependency.
/// to a downstream consumer (e.g. an Akka DPS <c>script-logs</c> topic). The concrete
/// implementation is <c>DpsScriptLogPublisher</c> (Runtime project), wired via DI; the
/// sink depends only on this interface so the Core.Scripting layer has no Akka dependency.
/// </summary>
public interface IScriptLogPublisher
{
@@ -7,7 +7,7 @@ namespace ZB.MOM.WW.OtOpcUa.Core.Scripting;
/// <summary>
/// Serilog sink that converts each script <see cref="LogEvent"/> into a
/// <see cref="ScriptLogEntry"/> and forwards it to an <see cref="IScriptLogPublisher"/>.
/// The publisher implementation (supplied by a later task) routes the entry onto the
/// The production publisher (<c>DpsScriptLogPublisher</c>) routes the entry onto the
/// Akka DPS <c>script-logs</c> topic so the live Script-log Admin UI page can display it.
/// </summary>
/// <remarks>
@@ -17,9 +17,9 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Browse;
/// <item>Folder per gobject; variables placed inside their owner folder.</item>
/// <item>Variable's full reference = <c>tag_name.attribute_name</c> — the format MXAccess
/// expects for read/write addressing (translated from the contained-name browse path).</item>
/// <item>Hierarchy is rendered flat (one folder per gobject under the driver root) for
/// this PR. PR 4.W's address-space wiring revisits whether to nest under
/// <c>parent_gobject_id</c> for a true tree shape.</item>
/// <item>Hierarchy is rendered flat (one folder per gobject under the driver root).
/// Nesting under <c>parent_gobject_id</c> for a true tree shape is not implemented;
/// the flat layout is the current shipping behaviour.</item>
/// </list>
/// </remarks>
public sealed class GalaxyDiscoverer
@@ -863,12 +863,12 @@ public sealed class GalaxyDriver
if (_dataWriter is null)
{
// Mirror the IReadable fallback: production write path runs on top of
// GalaxyMxSession (PR 4.2 skeleton; PR 4.4 wires the live session). Until
// that lands, deployments selecting Galaxy:Backend=mxgateway can't write.
// GatewayGalaxyDataWriter, which is wired by InitializeAsync when the gRPC session
// connects. This guard fires only if the driver is called before initialization completes.
throw new NotSupportedException(
"GalaxyDriver.WriteAsync requires GatewayGalaxyDataWriter wired against a connected " +
"GalaxyMxSession (PR 4.4). Until that lands, route writes through the legacy-host " +
"backend (Galaxy:Backend=legacy-host).");
"GalaxyMxSession. Call InitializeAsync and wait for a successful connection before " +
"issuing writes.");
}
return _dataWriter.WriteAsync(writes, ResolveSecurity, cancellationToken);
@@ -887,7 +887,7 @@ public sealed class GalaxyDriver
{
throw new NotSupportedException(
"GalaxyDriver.SubscribeAsync requires a connected GalaxyMxSession + GatewayGalaxySubscriber. " +
"PR 4.W wires the production session; until then route subscriptions through the legacy-host backend.");
"Call InitializeAsync and wait for a successful connection before subscribing.");
}
var pump = EnsureEventPumpStarted();
@@ -1103,7 +1103,7 @@ public sealed class GalaxyDriver
{
throw new NotSupportedException(
"GalaxyDriver.AcknowledgeAsync requires GatewayGalaxyAlarmAcknowledger wired against a connected " +
"GalaxyMxSession (PR B.2). InitializeAsync must run before alarm acknowledgements can flow.");
"GalaxyMxSession. InitializeAsync must complete successfully before alarm acknowledgements can flow.");
}
// Acks are issued one-by-one — the gateway RPC accepts a single alarm
@@ -18,9 +18,10 @@ namespace ZB.MOM.WW.OtOpcUa.AdminUI.ScriptAnalysis;
/// <see cref="VirtualTagContext"/> context.
/// </summary>
/// <remarks>
/// Public methods are placeholders returning empty results — later tasks fill in each
/// capability via TDD. The shared <see cref="Analyze"/> seam + the offset helpers are
/// the load-bearing part every later capability reuses; keep them even while unused.
/// All capabilities are fully implemented: Diagnose, Complete, Hover, SignatureHelp, and Format
/// are wired and backed by the real Roslyn document/analysis pipeline. Only InlayHints is
/// intentionally a no-op (empty list) — the endpoint exists for future use but the feature is
/// not implemented.
/// </remarks>
public sealed class ScriptAnalysisService
{
@@ -41,8 +41,10 @@ namespace ZB.MOM.WW.OtOpcUa.Runtime.Drivers;
/// <item><c>Stale</c> — ConfigDb unreachable on bootstrap. Background reconnect loop tries to advance.</item>
/// </list>
///
/// Children (DriverInstance/VirtualTag/etc.) are spawned in Phase 6 follow-up tasks (41-44).
/// For now the dispatch handler treats the apply as a no-op and writes the ACK back.
/// Children (DriverInstance/VirtualTag/etc.) are fully wired: <c>DispatchDeployment</c> drives
/// <see cref="PushDesiredSubscriptions"/> which runs the spawn-plan via <see cref="IDriverFactory"/>,
/// maintains the <c>FullName→NodeId</c> live-value routing map, and forwards results to the
/// OPC UA publish actor via <c>ForwardToMux</c>.
/// </summary>
public sealed class DriverHostActor : ReceiveActor, IWithTimers
{
@@ -243,13 +243,14 @@ public sealed class OpcUaPublishActor : ReceiveActor
_applier.MaterialiseScriptedAlarms(composition);
// Equipment-namespace tags get their own pass: ensures each signal's Variable (and any
// FolderPath sub-folder) exists under its already-materialised equipment folder so
// clients can browse them. Live values arrive in a later milestone; until then the
// variables show BadWaitingForInitialData.
// clients can browse them. Live values are pushed by DriverHostActor.ForwardToMux after
// each subscription cycle; variables show BadWaitingForInitialData only until the first
// publish interval fires.
_applier.MaterialiseEquipmentTags(composition);
// Equipment-namespace VirtualTags get their own pass right after the equipment tags:
// ensures each computed signal's Variable (and any FolderPath sub-folder) exists under its
// equipment folder with a folder-scoped NodeId. The VirtualTagActor fills live values in a
// later milestone; until then the variables show BadWaitingForInitialData (same as tags).
// equipment folder with a folder-scoped NodeId. VirtualTagHostActor.OnResult pushes live
// values once the first dependency update arrives; until then variables show BadWaitingForInitialData.
_applier.MaterialiseEquipmentVirtualTags(composition);
OtOpcUaTelemetry.OpcUaSinkWrite.Add(1, new KeyValuePair<string, object?>("kind", "rebuild"));
@@ -62,10 +62,11 @@ public static class ServiceCollectionExtensions
// driver path) ends up with exactly one descriptor regardless of registration order.
services.TryAddSingleton<ILdapAuthService, OtOpcUaLdapAuthService>();
// Shared ZB.MOM.WW.Auth group→role mapper seam (Task 1.1, additive). Wraps the existing
// RoleMapper.Map + RoleMapper.Merge logic; the login flow is rewired to consume it in a
// later task. Scoped to match ILdapGroupRoleMappingService (DbContext-backed, registered
// Scoped) — a singleton here would capture the scoped DB service.
// Shared ZB.MOM.WW.Auth group→role mapper seam. Wraps the existing RoleMapper.Map +
// RoleMapper.Merge logic; consumed by AuthEndpoints.cs (/auth/login) and by
// LdapOpcUaUserAuthenticator (OPC UA UserName session auth). Scoped to match
// ILdapGroupRoleMappingService (DbContext-backed, registered Scoped) — a singleton here
// would capture the scoped DB service.
services.TryAddScoped<IGroupRoleMapper<string>, OtOpcUaGroupRoleMapper>();
services.AddDataProtection()