feat(auditlog): ParentExecutionId column on AuditEvent + central AuditLog

src/ScadaLink.Commons/Entities/Audit/AuditEvent.cs

@@ -33,6 +33,13 @@ public sealed record AuditEvent
     /// </summary>
     public Guid? ExecutionId { get; init; }
 
+    /// <summary>
+    /// <see cref="ExecutionId"/> of the execution that spawned this run, when this
+    /// run was spawned by another; null for top-level runs. Lets a spawned
+    /// execution point back at its spawner for cross-run correlation.
+    /// </summary>
+    public Guid? ParentExecutionId { get; init; }
+
     /// <summary>Site id where the action originated; null for central-direct events.</summary>
     public string? SourceSiteId { get; init; }
 

src/ScadaLink.Commons/Types/Audit/AuditLogQueryFilter.cs

@@ -12,8 +12,8 @@ namespace ScadaLink.Commons.Types.Audit;
 /// the spec sense — <see cref="FromUtc"/> is inclusive and <see cref="ToUtc"/> is
 /// inclusive of the upper bound; the repository SQL uses <c>&gt;=</c> / <c>&lt;=</c>
 /// respectively. All filter dimensions are AND-combined with one another. The
-/// single-value <see cref="CorrelationId"/> and <see cref="ExecutionId"/>
+/// single-value <see cref="CorrelationId"/>, <see cref="ExecutionId"/> and
-/// dimensions constrain on equality when set.
+/// <see cref="ParentExecutionId"/> dimensions constrain on equality when set.
 /// </summary>
 public sealed record AuditLogQueryFilter(
     IReadOnlyList<AuditChannel>? Channels = null,
@@ -24,5 +24,6 @@ public sealed record AuditLogQueryFilter(
     string? Actor = null,
     Guid? CorrelationId = null,
     Guid? ExecutionId = null,
+    Guid? ParentExecutionId = null,
     DateTime? FromUtc = null,
     DateTime? ToUtc = null);

src/ScadaLink.ConfigurationDatabase/Configurations/AuditLogEntityTypeConfiguration.cs

@@ -93,6 +93,10 @@ public class AuditLogEntityTypeConfiguration : IEntityTypeConfiguration<AuditEve
             .HasFilter("[ExecutionId] IS NOT NULL")
             .HasDatabaseName("IX_AuditLog_Execution");
 
+        builder.HasIndex(e => e.ParentExecutionId)
+            .HasFilter("[ParentExecutionId] IS NOT NULL")
+            .HasDatabaseName("IX_AuditLog_ParentExecution");
+
         builder.HasIndex(e => new { e.Channel, e.Status, e.OccurredAtUtc })
             .IsDescending(false, false, true)
             .HasDatabaseName("IX_AuditLog_Channel_Status_Occurred");

src/ScadaLink.ConfigurationDatabase/Migrations/20260521210254_AddAuditLogParentExecutionId.cs

@@ -0,0 +1,59 @@
+using System;
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace ScadaLink.ConfigurationDatabase.Migrations
+{
+    /// <summary>
+    /// Adds the <c>ParentExecutionId</c> correlation column to the centralized
+    /// <c>AuditLog</c> table (#23). <c>ParentExecutionId</c> carries the
+    /// <c>ExecutionId</c> of the execution that spawned this run, letting a
+    /// spawned execution point back at its spawner — a sibling to the universal
+    /// per-run <c>ExecutionId</c>.
+    ///
+    /// The change is purely additive:
+    /// 1. <c>ParentExecutionId uniqueidentifier NULL</c> is added with no default,
+    ///    so the operation is a metadata-only <c>ALTER TABLE … ADD</c> — it does
+    ///    NOT rewrite the monthly-partitioned <c>AuditLog</c> table, and
+    ///    historical rows stay <c>NULL</c> (no backfill).
+    /// 2. <c>IX_AuditLog_ParentExecution</c> is created via raw SQL so it lands on
+    ///    the <c>ps_AuditLog_Month(OccurredAtUtc)</c> partition scheme, matching
+    ///    every other <c>IX_AuditLog_*</c> index. Keeping it partition-aligned
+    ///    preserves the partition-switch purge path (see
+    ///    AuditLogRepository.SwitchOutPartitionAsync).
+    /// </summary>
+    public partial class AddAuditLogParentExecutionId : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.AddColumn<Guid>(
+                name: "ParentExecutionId",
+                table: "AuditLog",
+                type: "uniqueidentifier",
+                nullable: true);
+
+            // Raw SQL so the index is created on the partition scheme — EF's
+            // CreateIndex cannot express the ON ps_AuditLog_Month(OccurredAtUtc)
+            // clause. Mirrors IX_AuditLog_Execution (filtered, aligned).
+            migrationBuilder.Sql(@"
+CREATE NONCLUSTERED INDEX IX_AuditLog_ParentExecution
+ON dbo.AuditLog (ParentExecutionId)
+WHERE ParentExecutionId IS NOT NULL
+ON ps_AuditLog_Month(OccurredAtUtc);");
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.Sql(@"
+IF EXISTS (SELECT 1 FROM sys.indexes WHERE name = 'IX_AuditLog_ParentExecution' AND object_id = OBJECT_ID('dbo.AuditLog'))
+    DROP INDEX IX_AuditLog_ParentExecution ON dbo.AuditLog;");
+
+            migrationBuilder.DropColumn(
+                name: "ParentExecutionId",
+                table: "AuditLog");
+        }
+    }
+}

src/ScadaLink.ConfigurationDatabase/Migrations/ScadaLinkDbContextModelSnapshot.cs

@@ -96,6 +96,9 @@ namespace ScadaLink.ConfigurationDatabase.Migrations
                         .IsUnicode(false)
                         .HasColumnType("varchar(32)");
 
+                    b.Property<Guid?>("ParentExecutionId")
+                        .HasColumnType("uniqueidentifier");
+
                     b.Property<bool>("PayloadTruncated")
                         .HasColumnType("bit");
 
@@ -149,6 +152,10 @@ namespace ScadaLink.ConfigurationDatabase.Migrations
                         .IsDescending()
                         .HasDatabaseName("IX_AuditLog_OccurredAtUtc");
 
+                    b.HasIndex("ParentExecutionId")
+                        .HasDatabaseName("IX_AuditLog_ParentExecution")
+                        .HasFilter("[ParentExecutionId] IS NOT NULL");
+
                     b.HasIndex("SourceSiteId", "OccurredAtUtc")
                         .IsDescending(false, true)
                         .HasDatabaseName("IX_AuditLog_Site_Occurred");

src/ScadaLink.ConfigurationDatabase/Repositories/AuditLogRepository.cs

@@ -64,12 +64,12 @@ public class AuditLogRepository : IAuditLogRepository
             await _context.Database.ExecuteSqlInterpolatedAsync(
                 $@"IF NOT EXISTS (SELECT 1 FROM dbo.AuditLog WHERE EventId = {evt.EventId})
 INSERT INTO dbo.AuditLog
-    (EventId, OccurredAtUtc, IngestedAtUtc, Channel, Kind, CorrelationId, ExecutionId,
+    (EventId, OccurredAtUtc, IngestedAtUtc, Channel, Kind, CorrelationId, ExecutionId, ParentExecutionId,
      SourceSiteId, SourceInstanceId, SourceScript, Actor, Target, Status,
      HttpStatus, DurationMs, ErrorMessage, ErrorDetail, RequestSummary,
      ResponseSummary, PayloadTruncated, Extra, ForwardState)
 VALUES
-    ({evt.EventId}, {evt.OccurredAtUtc}, {evt.IngestedAtUtc}, {channel}, {kind}, {evt.CorrelationId}, {evt.ExecutionId},
+    ({evt.EventId}, {evt.OccurredAtUtc}, {evt.IngestedAtUtc}, {channel}, {kind}, {evt.CorrelationId}, {evt.ExecutionId}, {evt.ParentExecutionId},
      {evt.SourceSiteId}, {evt.SourceInstanceId}, {evt.SourceScript}, {evt.Actor}, {evt.Target}, {status},
      {evt.HttpStatus}, {evt.DurationMs}, {evt.ErrorMessage}, {evt.ErrorDetail}, {evt.RequestSummary},
      {evt.ResponseSummary}, {evt.PayloadTruncated}, {evt.Extra}, {forwardState});",
@@ -162,6 +162,11 @@ VALUES
             query = query.Where(e => e.ExecutionId == executionId);
         }
 
+        if (filter.ParentExecutionId is { } parentExecutionId)
+        {
+            query = query.Where(e => e.ParentExecutionId == parentExecutionId);
+        }
+
         if (filter.FromUtc is { } fromUtc)
         {
             query = query.Where(e => e.OccurredAtUtc >= fromUtc);
@@ -268,10 +273,13 @@ VALUES
                 PayloadTruncated   bit              NOT NULL,
                 Extra              nvarchar(max)    NULL,
                 ForwardState       varchar(32)      NULL,
-                -- ExecutionId is last because it was added to the live AuditLog table by a later
+                -- ExecutionId and ParentExecutionId are last (in this ordinal order)
-                -- ALTER TABLE ADD migration; the staging table must match the live table column
+                -- because each was added to the live AuditLog table by a later
-                -- shape ordinal-for-ordinal or ALTER TABLE ... SWITCH PARTITION fails.
+                -- ALTER TABLE ADD migration; the staging table must match the live
+                -- table column shape ordinal-for-ordinal or
+                -- ALTER TABLE ... SWITCH PARTITION fails.
                 ExecutionId        uniqueidentifier NULL,
+                ParentExecutionId  uniqueidentifier NULL,
                 CONSTRAINT PK_{stagingTableName} PRIMARY KEY CLUSTERED (EventId, OccurredAtUtc)
             ) ON [PRIMARY];
 

tests/ScadaLink.ConfigurationDatabase.Tests/Configurations/AuditLogEntityTypeConfigurationTests.cs

@@ -74,9 +74,10 @@ public class AuditLogEntityTypeConfigurationTests : IDisposable
             .Where(p => !p.IsShadowProperty())
             .ToList();
 
-        // AuditEvent record exposes 22 init-only properties (alog.md §4 plus the
+        // AuditEvent record exposes 23 init-only properties (alog.md §4 plus the
-        // additive ExecutionId universal correlation column).
+        // additive ExecutionId universal correlation column and its
-        Assert.Equal(22, properties.Count);
+        // ParentExecutionId sibling).
+        Assert.Equal(23, properties.Count);
     }
 
     [Fact]
@@ -92,13 +93,15 @@ public class AuditLogEntityTypeConfigurationTests : IDisposable
 
         // Five reconciliation/query indexes from alog.md §4, plus the EventId unique
         // index introduced alongside the composite PK (Bundle C), plus the additive
-        // IX_AuditLog_Execution index supporting ExecutionId lookups.
+        // IX_AuditLog_Execution index supporting ExecutionId lookups and the
+        // IX_AuditLog_ParentExecution index supporting ParentExecutionId lookups.
         var expected = new[]
         {
             "IX_AuditLog_Channel_Status_Occurred",
             "IX_AuditLog_CorrelationId",
             "IX_AuditLog_Execution",
             "IX_AuditLog_OccurredAtUtc",
+            "IX_AuditLog_ParentExecution",
             "IX_AuditLog_Site_Occurred",
             "IX_AuditLog_Target_Occurred",
             "UX_AuditLog_EventId",
@@ -143,5 +146,9 @@ public class AuditLogEntityTypeConfigurationTests : IDisposable
         var executionIdx = entity.GetIndexes()
             .Single(i => i.GetDatabaseName() == "IX_AuditLog_Execution");
         Assert.Equal("[ExecutionId] IS NOT NULL", executionIdx.GetFilter());
+
+        var parentExecutionIdx = entity.GetIndexes()
+            .Single(i => i.GetDatabaseName() == "IX_AuditLog_ParentExecution");
+        Assert.Equal("[ParentExecutionId] IS NOT NULL", parentExecutionIdx.GetFilter());
     }
 }

tests/ScadaLink.ConfigurationDatabase.Tests/Repositories/AuditLogRepositoryTests.cs

@@ -275,6 +275,35 @@ public class AuditLogRepositoryTests : IClassFixture<MsSqlMigrationFixture>
         Assert.All(rows, r => Assert.Equal(executionId, r.ExecutionId));
     }
 
+    [SkippableFact]
+    public async Task QueryAsync_FilterByParentExecutionId_ReturnsMatchingRows()
+    {
+        Skip.IfNot(_fixture.Available, _fixture.SkipReason);
+
+        var siteId = NewSiteId();
+        await using var context = CreateContext();
+        var repo = new AuditLogRepository(context);
+
+        var parentExecutionId = Guid.NewGuid();
+        var t0 = new DateTime(2026, 5, 3, 13, 0, 0, DateTimeKind.Utc);
+        // Two rows share the ParentExecutionId; one carries a different
+        // ParentExecutionId and one leaves it null — both must be excluded by the
+        // single-value filter.
+        await repo.InsertIfNotExistsAsync(NewEvent(siteId, occurredAtUtc: t0, parentExecutionId: parentExecutionId));
+        await repo.InsertIfNotExistsAsync(NewEvent(siteId, occurredAtUtc: t0.AddMinutes(1), parentExecutionId: parentExecutionId));
+        await repo.InsertIfNotExistsAsync(NewEvent(siteId, occurredAtUtc: t0.AddMinutes(2), parentExecutionId: Guid.NewGuid()));
+        await repo.InsertIfNotExistsAsync(NewEvent(siteId, occurredAtUtc: t0.AddMinutes(3), parentExecutionId: null));
+
+        var rows = await repo.QueryAsync(
+            new AuditLogQueryFilter(
+                SourceSiteIds: new[] { siteId },
+                ParentExecutionId: parentExecutionId),
+            new AuditLogPaging(PageSize: 10));
+
+        Assert.Equal(2, rows.Count);
+        Assert.All(rows, r => Assert.Equal(parentExecutionId, r.ParentExecutionId));
+    }
+
     [SkippableFact]
     public async Task QueryAsync_FilterByTimeRange()
     {
@@ -754,7 +783,8 @@ public class AuditLogRepositoryTests : IClassFixture<MsSqlMigrationFixture>
         AuditKind kind = AuditKind.ApiCall,
         AuditStatus status = AuditStatus.Delivered,
         string? errorMessage = null,
-        Guid? executionId = null) =>
+        Guid? executionId = null,
+        Guid? parentExecutionId = null) =>
         new()
         {
             EventId = Guid.NewGuid(),
@@ -765,5 +795,6 @@ public class AuditLogRepositoryTests : IClassFixture<MsSqlMigrationFixture>
             SourceSiteId = siteId,
             ErrorMessage = errorMessage,
             ExecutionId = executionId,
+            ParentExecutionId = parentExecutionId,
         };
 }