feat(siteruntime): Tracking.Status(id) script API (#23 M3)

src/ScadaLink.SiteRuntime/Scripts/ScriptRuntimeContext.cs

@@ -4,6 +4,7 @@ using System.Text.RegularExpressions;
 using Akka.Actor;
 using Microsoft.Extensions.Logging;
 using ScadaLink.Commons.Entities.Audit;
+using ScadaLink.Commons.Interfaces;
 using ScadaLink.Commons.Interfaces.Services;
 using ScadaLink.Commons.Messages.Instance;
 using ScadaLink.Commons.Messages.Notification;
@@ -85,6 +86,14 @@ public class ScriptRuntimeContext
     /// </summary>
     private readonly IAuditWriter? _auditWriter;
 
+    /// <summary>
+    /// Audit Log #23 (M3): site-local tracking store consulted by
+    /// <c>Tracking.Status(TrackedOperationId)</c>. Optional — when null the
+    /// helper throws on access, mirroring the existing
+    /// "service-not-wired" behaviour of the other integration helpers.
+    /// </summary>
+    private readonly IOperationTrackingStore? _operationTrackingStore;
+
     public ScriptRuntimeContext(
         IActorRef instanceActor,
         IActorRef self,
@@ -100,7 +109,8 @@ public class ScriptRuntimeContext
         ICanTell? siteCommunicationActor = null,
         string siteId = "",
         string? sourceScript = null,
-        IAuditWriter? auditWriter = null)
+        IAuditWriter? auditWriter = null,
+        IOperationTrackingStore? operationTrackingStore = null)
     {
         _instanceActor = instanceActor;
         _self = self;
@@ -117,6 +127,7 @@ public class ScriptRuntimeContext
         _siteId = siteId;
         _sourceScript = sourceScript;
         _auditWriter = auditWriter;
+        _operationTrackingStore = operationTrackingStore;
     }
 
     /// <summary>
@@ -235,6 +246,15 @@ public class ScriptRuntimeContext
     public NotifyHelper Notify => new(
         _storeAndForward, _siteCommunicationActor, _siteId, _instanceName, _sourceScript, _askTimeout, _logger);
 
+    /// <summary>
+    /// Audit Log #23 (M3): site-local tracking-status API for cached operations.
+    /// <c>Tracking.Status(trackedOperationId)</c> reads the site SQLite tracking row
+    /// directly (authoritative source of truth — no central round-trip) and
+    /// returns a <see cref="TrackingStatusSnapshot"/>, or <c>null</c> when the
+    /// id is unknown / has already been purged.
+    /// </summary>
+    public TrackingHelper Tracking => new(_operationTrackingStore, _logger);
+
     /// <summary>
     /// Helper class for Scripts.CallShared() syntax.
     /// </summary>
@@ -746,4 +766,46 @@ public class ScriptRuntimeContext
             return notificationId;
         }
     }
+
+    /// <summary>
+    /// Audit Log #23 (M3): script-side accessor for cached-operation tracking.
+    /// <c>Tracking.Status(trackedOperationId)</c> reads the site-local SQLite
+    /// row directly via <see cref="IOperationTrackingStore.GetStatusAsync"/> —
+    /// the site is the single source of truth for cached-call status, so no
+    /// central round-trip is needed and the call is answered authoritatively.
+    /// </summary>
+    public class TrackingHelper
+    {
+        private readonly IOperationTrackingStore? _store;
+        private readonly ILogger _logger;
+
+        internal TrackingHelper(IOperationTrackingStore? store, ILogger logger)
+        {
+            _store = store;
+            _logger = logger;
+        }
+
+        /// <summary>
+        /// Returns the latest tracking snapshot for the supplied id, or
+        /// <c>null</c> when the id is unknown (never recorded, or purged after
+        /// the retention window).
+        /// </summary>
+        /// <exception cref="InvalidOperationException">
+        /// Thrown when the script runtime was constructed without an
+        /// <see cref="IOperationTrackingStore"/> — mirrors the
+        /// "service-not-wired" failure mode of the other integration helpers.
+        /// </exception>
+        public Task<TrackingStatusSnapshot?> Status(
+            TrackedOperationId trackedOperationId,
+            CancellationToken cancellationToken = default)
+        {
+            if (_store == null)
+            {
+                throw new InvalidOperationException(
+                    "Operation tracking store not available");
+            }
+
+            return _store.GetStatusAsync(trackedOperationId, cancellationToken);
+        }
+    }
 }