feat(siteruntime): OperationTrackingStore site-local SQLite (#23 M3)

src/ScadaLink.Commons/Interfaces/IOperationTrackingStore.cs

@@ -0,0 +1,87 @@
+using ScadaLink.Commons.Types;
+
+namespace ScadaLink.Commons.Interfaces;
+
+/// <summary>
+/// Site-local source of truth for cached-operation tracking
+/// (<c>ExternalSystem.CachedCall</c> / <c>Database.CachedWrite</c>) — alongside the
+/// Store-and-Forward buffer, this is the row that <c>Tracking.Status(id)</c>
+/// reads (Audit Log #23 / M3). One row per <see cref="TrackedOperationId"/>;
+/// terminal rows are purged after a configurable retention window
+/// (default 7 days).
+/// </summary>
+/// <remarks>
+/// <para>
+/// The store is intentionally a thin write-API on top of SQLite — not a
+/// dispatcher. Status transitions follow
+/// <c>Submitted → Retrying → Delivered / Parked / Failed / Discarded</c>; rows
+/// in a terminal state never roll back. Implementations must:
+/// <list type="bullet">
+///   <item><description><see cref="RecordEnqueueAsync"/> is insert-if-not-exists
+///   (caller-supplied id is the idempotency key — duplicate enqueues are no-ops).</description></item>
+///   <item><description><see cref="RecordAttemptAsync"/> only updates non-terminal rows.</description></item>
+///   <item><description><see cref="RecordTerminalAsync"/> only flips a non-terminal row to terminal.</description></item>
+///   <item><description><see cref="PurgeTerminalAsync"/> deletes terminal rows whose
+///   <c>TerminalAtUtc</c> is strictly older than the supplied threshold.</description></item>
+/// </list>
+/// </para>
+/// </remarks>
+public interface IOperationTrackingStore
+{
+    /// <summary>
+    /// Insert a new tracking row in <c>Submitted</c> state with <c>RetryCount = 0</c>.
+    /// Idempotent — a duplicate id is silently ignored (the existing row is left
+    /// untouched), matching the at-least-once semantics of the calling site
+    /// store-and-forward path.
+    /// </summary>
+    Task RecordEnqueueAsync(
+        TrackedOperationId id,
+        string kind,
+        string? targetSummary,
+        string? sourceInstanceId,
+        string? sourceScript,
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Advance an in-flight tracking row's status, retry counter, and most-
+    /// recent error/HTTP-status. Terminal rows (<see cref="RecordTerminalAsync"/>
+    /// already applied) are NOT mutated — the operation has reached its final
+    /// outcome and any late-arriving attempt telemetry is dropped on the floor.
+    /// </summary>
+    Task RecordAttemptAsync(
+        TrackedOperationId id,
+        string status,
+        int retryCount,
+        string? lastError,
+        int? httpStatus,
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Flip a non-terminal tracking row to terminal — sets
+    /// <c>TerminalAtUtc = now</c> and writes the final status / error. A row
+    /// already in terminal state is left untouched (first-write-wins).
+    /// </summary>
+    Task RecordTerminalAsync(
+        TrackedOperationId id,
+        string status,
+        string? lastError,
+        int? httpStatus,
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Return the latest snapshot for the supplied id, or <c>null</c> when no
+    /// tracking row exists (purged or never recorded).
+    /// </summary>
+    Task<TrackingStatusSnapshot?> GetStatusAsync(
+        TrackedOperationId id,
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Delete terminal rows whose <c>TerminalAtUtc</c> is strictly older than
+    /// <paramref name="olderThanUtc"/>. Non-terminal rows are kept regardless
+    /// of age (the operation is still in flight).
+    /// </summary>
+    Task PurgeTerminalAsync(
+        DateTime olderThanUtc,
+        CancellationToken ct = default);
+}

src/ScadaLink.Commons/Types/TrackingStatusSnapshot.cs

@@ -0,0 +1,40 @@
+namespace ScadaLink.Commons.Types;
+
+/// <summary>
+/// Site-local snapshot of a cached operation's tracking state, returned by the
+/// <c>Tracking.Status(TrackedOperationId)</c> script API (Audit Log #23 / M3).
+/// </summary>
+/// <param name="Id">Tracking handle returned by <c>CachedCall</c>/<c>CachedWrite</c>.</param>
+/// <param name="Kind">
+/// Operation category — <c>"ApiCallCached"</c> or <c>"DbWriteCached"</c> — mirroring
+/// the <see cref="ScadaLink.Commons.Types.Enums.AuditKind"/> per-attempt vocabulary.
+/// </param>
+/// <param name="TargetSummary">
+/// Human-readable target (e.g. <c>"ERP.GetOrder"</c> or <c>"WarehouseDb"</c>); may be
+/// null for early-lifecycle rows recorded before the target was resolved.
+/// </param>
+/// <param name="Status">
+/// Lifecycle status — one of <c>Submitted</c>, <c>Forwarded</c>, <c>Retrying</c>,
+/// <c>Attempted</c>, <c>Delivered</c>, <c>Failed</c>, <c>Parked</c>, <c>Discarded</c>.
+/// </param>
+/// <param name="RetryCount">Number of attempts made; 0 prior to first dispatch.</param>
+/// <param name="LastError">Most recent error message; null while non-terminal-and-no-failures.</param>
+/// <param name="HttpStatus">Most recent HTTP status code where applicable; null otherwise.</param>
+/// <param name="CreatedAtUtc">UTC timestamp the tracking row was first recorded.</param>
+/// <param name="UpdatedAtUtc">UTC timestamp of the latest status mutation.</param>
+/// <param name="TerminalAtUtc">UTC timestamp the row reached a terminal status; null while still active.</param>
+/// <param name="SourceInstanceId">Instance id that issued the cached call, when known.</param>
+/// <param name="SourceScript">Script that issued the cached call, when known.</param>
+public sealed record TrackingStatusSnapshot(
+    TrackedOperationId Id,
+    string Kind,
+    string? TargetSummary,
+    string Status,
+    int RetryCount,
+    string? LastError,
+    int? HttpStatus,
+    DateTime CreatedAtUtc,
+    DateTime UpdatedAtUtc,
+    DateTime? TerminalAtUtc,
+    string? SourceInstanceId,
+    string? SourceScript);