feat(siteeventlog): emit store_and_forward + notification events (M1.7)

StoreAndForwardService gains an optional ISiteEventLogger? ctor param (default
null so the many direct-construction tests still compile) and, when wired,
mirrors its own buffer/retry/park activity onto site operational events via the
existing OnActivity hook (which already isolates a throwing subscriber, so a
failing event log can never be misclassified as a transient delivery failure):

- store_and_forward (ExternalSystem / CachedDbWrite): queued/retried/delivered/
  parked. Warning on buffer/retry, Error on park, Info on retry-recovery; an
  immediate-success delivery is the hot path and is not logged.
- notification (the site forward-to-central path): logged ONLY on forward
  FAILURE (buffered after the immediate forward threw) and on park, per the
  Component-SiteEventLogging spec — routine enqueue and forward-success are
  deliberately not logged (central's Notifications table is the audit record).

Wired through AddStoreAndForward (resolves ISiteEventLogger optionally from DI);
StoreAndForward project now references SiteEventLogging (acyclic: SiteEventLogging
references only Commons). Also documents the 'notification' category on the
ISiteEventLogger.LogEventAsync eventType param (folds in M1.8 doc fix).

src/ZB.MOM.WW.ScadaBridge.SiteEventLogging/ISiteEventLogger.cs

@@ -11,7 +11,7 @@ public interface ISiteEventLogger
     /// <see cref="Task"/> completes once the event is durably persisted and faults if
     /// the write fails, so callers that <c>await</c> it observe success or failure.
     /// </summary>
-    /// <param name="eventType">Category: script, alarm, deployment, connection, store_and_forward, instance_lifecycle</param>
+    /// <param name="eventType">Category: script, alarm, deployment, connection, store_and_forward, instance_lifecycle, notification</param>
     /// <param name="severity">Info, Warning, or Error</param>
     /// <param name="instanceId">Optional instance ID associated with the event</param>
     /// <param name="source">Source identifier, e.g., "ScriptActor:MonitorSpeed"</param>

src/ZB.MOM.WW.ScadaBridge.StoreAndForward/ServiceCollectionExtensions.cs

@@ -2,6 +2,7 @@ using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Options;
 using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services;
+using ZB.MOM.WW.ScadaBridge.SiteEventLogging;
 
 namespace ZB.MOM.WW.ScadaBridge.StoreAndForward;
 
@@ -49,13 +50,19 @@ public static class ServiceCollectionExtensions
             // observable in the central audit log instead of producing a
             // silent empty-string SourceSite.
             var siteId = siteContext?.SiteId ?? string.Empty;
+            // M1.7: optional site operational-event log. Resolved through
+            // GetService so a host (or test) that has not called
+            // AddSiteEventLogging simply gets null and the S&F activity stays
+            // a no-op for site-event purposes.
+            var siteEventLogger = sp.GetService<ISiteEventLogger>();
             return new StoreAndForwardService(
                 storage,
                 options,
                 logger,
                 replication,
                 cachedCallObserver,
-                siteId);
+                siteId,
+                siteEventLogger);
         });
 
         services.AddSingleton<ReplicationService>(sp =>

src/ZB.MOM.WW.ScadaBridge.StoreAndForward/StoreAndForwardService.cs

@@ -3,6 +3,7 @@ using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services;
 using ZB.MOM.WW.ScadaBridge.Commons.Observability;
 using ZB.MOM.WW.ScadaBridge.Commons.Types;
 using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
+using ZB.MOM.WW.ScadaBridge.SiteEventLogging;
 
 namespace ZB.MOM.WW.ScadaBridge.StoreAndForward;
 
@@ -44,6 +45,15 @@ public class StoreAndForwardService
     /// </summary>
     private readonly ICachedCallLifecycleObserver? _cachedCallObserver;
     /// <summary>
+    /// M1.7: optional site operational-event log. When non-null the service maps
+    /// its own buffer/retry/park activity (the same activity that drives
+    /// <see cref="OnActivity"/>) onto site events — <c>store_and_forward</c> for the
+    /// cached-call categories and <c>notification</c> for the site's
+    /// forward-to-central notification path. Best-effort and fire-and-forget so a
+    /// failing logger never affects delivery bookkeeping.
+    /// </summary>
+    private readonly ISiteEventLogger? _siteEventLogger;
+    /// <summary>
     /// Audit Log #23 (M3 Bundle E — Task E4): site id stamped onto the
     /// cached-call attempt context so the audit bridge can build the
     /// <see cref="SiteCallOperational"/> half of the telemetry packet.
@@ -173,13 +183,20 @@ public class StoreAndForwardService
     /// <param name="replication">Optional replication service for standby synchronization.</param>
     /// <param name="cachedCallObserver">Optional observer for cached call lifecycle events.</param>
     /// <param name="siteId">The site identifier this service belongs to.</param>
+    /// <param name="siteEventLogger">
+    /// M1.7: optional site operational-event log. When non-null, buffer/retry/park
+    /// activity is mirrored to site events (<c>store_and_forward</c> /
+    /// <c>notification</c> by category). Optional with a <c>null</c> default so the
+    /// many direct-construction tests still compile unchanged.
+    /// </param>
     public StoreAndForwardService(
         StoreAndForwardStorage storage,
         StoreAndForwardOptions options,
         ILogger<StoreAndForwardService> logger,
         ReplicationService? replication = null,
         ICachedCallLifecycleObserver? cachedCallObserver = null,
-        string siteId = "")
+        string siteId = "",
+        ISiteEventLogger? siteEventLogger = null)
     {
         _storage = storage;
         _options = options;
@@ -191,6 +208,91 @@ public class StoreAndForwardService
         // audit pipeline keying off SourceSite) never see an empty string and
         // a misconfigured host is recognisable in the central log.
         _siteId = string.IsNullOrWhiteSpace(siteId) ? UnknownSiteSentinel : siteId;
+        _siteEventLogger = siteEventLogger;
+
+        // M1.7: ride the existing activity hook to emit site operational events.
+        // RaiseActivity already isolates a throwing subscriber, so a failing
+        // event log can never be misclassified as a transient delivery failure
+        // (StoreAndForward-009). Only subscribe when a logger is wired so the
+        // legacy (test/central) construction path stays a no-op.
+        if (_siteEventLogger != null)
+        {
+            OnActivity += EmitSiteEvent;
+        }
+    }
+
+    /// <summary>
+    /// M1.7: maps one store-and-forward activity to a site operational event,
+    /// following the Site Event Logging spec's per-category scope
+    /// (Component-SiteEventLogging.md §"Events Logged"):
+    /// <list type="bullet">
+    ///   <item><description>Cached-call categories
+    ///   (<see cref="StoreAndForwardCategory.ExternalSystem"/> /
+    ///   <see cref="StoreAndForwardCategory.CachedDbWrite"/>) log under
+    ///   <c>store_and_forward</c> for queued / retried / parked / retry-delivered
+    ///   activity.</description></item>
+    ///   <item><description>The site's notification forward-to-central path
+    ///   (<see cref="StoreAndForwardCategory.Notification"/>) logs under
+    ///   <c>notification</c> ONLY on a forward FAILURE (buffered after the
+    ///   immediate forward threw) or a park (long-buffered / retries exhausted).
+    ///   Routine enqueue and forward-success are deliberately NOT logged — central's
+    ///   <c>Notifications</c> table is the record of audit; the site only fills the
+    ///   in-transit blind spot when central is unreachable.</description></item>
+    /// </list>
+    /// A successful immediate cached-call <c>Delivered</c> is the normal hot path and
+    /// is not logged.
+    /// </summary>
+    private void EmitSiteEvent(string action, StoreAndForwardCategory category, string detail)
+    {
+        var logger = _siteEventLogger;
+        if (logger == null)
+        {
+            return;
+        }
+
+        // An immediate-delivery success is the normal hot path, not an
+        // operational event. A retry-loop success (detail "Delivered to … after
+        // N retries") IS logged for cached calls — it records a recovery.
+        if (action == "Delivered" && detail.StartsWith("Immediate", StringComparison.Ordinal))
+        {
+            return;
+        }
+
+        if (category == StoreAndForwardCategory.Notification)
+        {
+            // Spec: log only forward-failure (the immediate forward threw and the
+            // notification was buffered for retry — detail "Buffered for retry:")
+            // and park. A routine "No handler registered, buffered" enqueue and a
+            // forward-success "Delivered" are deliberately NOT logged.
+            var isForwardFailure = action == "Queued"
+                && detail.StartsWith("Buffered for retry", StringComparison.Ordinal);
+            if (!isForwardFailure && action != "Parked")
+            {
+                return;
+            }
+
+            var notifSeverity = action == "Parked" ? "Error" : "Warning";
+            _ = logger.LogEventAsync(
+                "notification", notifSeverity, instanceId: null,
+                source: "StoreAndForwardService",
+                message: $"Notification {action.ToLowerInvariant()}: {detail}");
+            return;
+        }
+
+        // Cached-call categories: queued / retried / parked / retry-delivered.
+        // Severity: parking is an Error (delivery abandoned for retry purposes);
+        // queue/retry/requeue are Warning; a retry-loop Delivered is Info.
+        var severity = action switch
+        {
+            "Parked" => "Error",
+            "Delivered" => "Info",
+            _ => "Warning",
+        };
+
+        _ = logger.LogEventAsync(
+            "store_and_forward", severity, instanceId: null,
+            source: "StoreAndForwardService",
+            message: $"Operation {action.ToLowerInvariant()}: {detail}");
     }
 
     /// <summary>

src/ZB.MOM.WW.ScadaBridge.StoreAndForward/ZB.MOM.WW.ScadaBridge.StoreAndForward.csproj

@@ -17,6 +17,7 @@
 
   <ItemGroup>
     <ProjectReference Include="../ZB.MOM.WW.ScadaBridge.Commons/ZB.MOM.WW.ScadaBridge.Commons.csproj" />
+    <ProjectReference Include="../ZB.MOM.WW.ScadaBridge.SiteEventLogging/ZB.MOM.WW.ScadaBridge.SiteEventLogging.csproj" />
   </ItemGroup>
 
   <ItemGroup>