Add invocation count for tracking job completion

CLAUDE.md

@@ -104,7 +104,9 @@ or with inline pages:
 }
 ```
 
-**`BuilderJob` entity** (PostgreSQL, snake_case naming): `Id`, `SourceUri`, `SourceDataJson`, `Status`, `Created`, `Started`, `Finished`, `TotalPages`, `PagesCompleted`, `TotalWordCount`, `TotalImageCount`, `Errors`, `HangfireJobId`, `Services` (bitmask), `Title`, `CustomTypesJson`.
+**`BuilderJob` entity** (PostgreSQL, snake_case naming): `Id`, `SourceUri`, `SourceDataJson`, `Status`, `Created`, `Started`, `Finished`, `TotalPages`, `PagesCompleted`, `TotalWordCount`, `TotalImageCount`, `Errors`, `HangfireJobId`, `Services` (bitmask), `Title`, `CustomTypesJson`, `InvocationCount`.
+
+**`InvocationCount`**: tracks how many times the job processor has run for this job. Set to `1` on initial `POST`, incremented by 1 on every `PUT` (reprocess). Existing rows default to `1`. Returned on the `POST`/`PUT`/`GET` `JobResponse` and included in `JobCompletionNotification`, so callers can tell which run a completion notification belongs to. Server-managed only — not settable by the caller.
 
 **`TextBuildJob`** (Hangfire): fetches manifest/resources concurrently (bounded by `MaxConcurrentPageFetches`), feeds `TextBuilder`, persists all artefacts, records per-page warnings without aborting the job.
 

src/TextServices.Builder.Api/Data/BuilderJob.cs

@@ -58,4 +58,11 @@ public class BuilderJob
     /// A value of 0 means processing completed but no derivatives could be produced.
     /// </summary>
     public int? FulfilledServices { get; set; }
+
+    /// <summary>
+    /// Number of times the job processor has been invoked for this job. Set to 1 on
+    /// initial creation (<c>POST</c>) and incremented by 1 on every reprocess (<c>PUT</c>),
+    /// so callers can tell which run a completion notification belongs to.
+    /// </summary>
+    public int InvocationCount { get; set; } = 1;
 }

src/TextServices.Builder.Api/Features/Jobs/JobResponse.cs

@@ -25,6 +25,12 @@ public class JobResponse
     public int TotalImageCount { get; set; }
     public string? Errors { get; set; }
 
+    /// <summary>
+    /// Number of times the job processor has been invoked for this job. 1 on initial
+    /// creation, incremented on every reprocess (<c>PUT</c>).
+    /// </summary>
+    public int InvocationCount { get; set; } = 1;
+
     /// <summary>
     /// The services that were actually produced during the most recent run.
     /// Null for jobs processed before this field was introduced.
@@ -119,6 +125,7 @@ public static JobResponse From(BuilderJob job, TextServicesOptions options)
             TotalWordCount = job.TotalWordCount,
             TotalImageCount = job.TotalImageCount,
             Errors = job.Errors,
+            InvocationCount = job.InvocationCount,
             SearchV1 = searchV1,
             AutocompleteV1 = autocompleteV1,
             SearchV2 = searchV2,

src/TextServices.Builder.Api/Features/Jobs/ReprocessJob.cs

@@ -61,6 +61,7 @@ public async Task<ReprocessJobResult> Handle(ReprocessJobRequest request, Cancel
         job.TotalImageCount = 0;
         job.Errors = null;
         job.HangfireJobId = null;
+        job.InvocationCount++;
 
         await db.SaveChangesAsync(ct);
 

src/TextServices.Builder.Api/Jobs/TextBuildJob.cs

@@ -83,7 +83,7 @@ public async Task ExecuteAsync(string jobId, IJobCancellationToken cancellationT
 
                 await jobNotifier.Notify(
                     new JobCompletionNotification(job.Id, job.Status, job.Finished,
-                        job.TotalPages, job.TotalWordCount, job.Errors),
+                        job.TotalPages, job.TotalWordCount, job.Errors, job.InvocationCount),
                     cancellationToken.ShutdownToken);
             }
             catch (Exception ex)
@@ -97,7 +97,7 @@ await jobNotifier.Notify(
 
                 await jobNotifier.Notify(
                     new JobCompletionNotification(job.Id, job.Status, job.Finished,
-                        job.TotalPages, job.TotalWordCount, job.Errors),
+                        job.TotalPages, job.TotalWordCount, job.Errors, job.InvocationCount),
                     cancellationToken.ShutdownToken);
             }
         }

src/TextServices.Builder.Api/Migrations/20260706104802_AddInvocationCountToBuilderJob.cs

@@ -0,0 +1,29 @@
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace TextServices.Builder.Api.Migrations
+{
+    /// <inheritdoc />
+    public partial class AddInvocationCountToBuilderJob : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.AddColumn<int>(
+                name: "invocation_count",
+                table: "jobs",
+                type: "integer",
+                nullable: false,
+                defaultValue: 1);
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropColumn(
+                name: "invocation_count",
+                table: "jobs");
+        }
+    }
+}

src/TextServices.Builder.Api/Migrations/BuilderDbContextModelSnapshot.cs

@@ -53,6 +53,10 @@ protected override void BuildModel(ModelBuilder modelBuilder)
                         .HasColumnType("text")
                         .HasColumnName("hangfire_job_id");
 
+                    b.Property<int>("InvocationCount")
+                        .HasColumnType("integer")
+                        .HasColumnName("invocation_count");
+
                     b.Property<int>("PagesCompleted")
                         .HasColumnType("integer")
                         .HasColumnName("pages_completed");

src/TextServices.Builder.Api/Services/Notifications/JobCompletionNotification.cs

@@ -8,4 +8,5 @@ public record JobCompletionNotification(
     DateTimeOffset? Finished,
     int TotalPages,
     int TotalWordCount,
-    string? Errors);
+    string? Errors,
+    int InvocationCount);

src/TextServices.Demo/wwwroot/builder.html

@@ -60,6 +60,7 @@ <h2 style="margin:0">Jobs</h2>
           <th>ID</th>
           <th>Source</th>
           <th>Status</th>
+          <th>Invocations</th>
           <th>Progress</th>
           <th>Words</th>
           <th>Actions</th>

src/TextServices.Demo/wwwroot/js/builder.js

@@ -195,6 +195,7 @@ function renderTable(rows) {
             <td><code style="font-size:0.8rem">${esc(id)}</code></td>
             <td style="max-width:200px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap" title="${esc(sourceUri)}">${esc(truncate(sourceUri, 50))}</td>
             <td><span class="status-badge status-${esc(status)}">${esc(status)}</span></td>
+            <td>${job?.invocationCount ?? '—'}</td>
             <td>${renderProgress(job)}</td>
             <td>${job?.totalWordCount != null ? job.totalWordCount.toLocaleString() : '—'}</td>
             <td class="actions-cell"></td>

src/TextServices.Search.Api/TextServices.Search.Api.csproj

@@ -12,6 +12,7 @@
     <PackageReference Include="AWSSDK.SecurityToken" Version="4.0.6.8" />
     <PackageReference Include="MediatR" Version="12.5.0" />
     <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.1" />
+    <PackageReference Include="Microsoft.OpenApi" Version="2.9.0" />
     <PackageReference Include="Serilog.AspNetCore" Version="10.0.0" />
     <PackageReference Include="Serilog.Enrichers.ClientInfo" Version="2.9.0" />
   </ItemGroup>

src/TextServices.Tests/BuilderApi/JobResponseTests.cs

@@ -22,6 +22,28 @@ private static BuilderJob CompletedJob(
             Status = JobStatus.Completed,
         };
 
+    // -------------------------------------------------------------------------
+    // InvocationCount — reflects the job's current run count
+    // -------------------------------------------------------------------------
+
+    [Fact]
+    public void From_NewJob_InvocationCountIsOne()
+    {
+        var response = JobResponse.From(CompletedJob(), Options());
+        response.InvocationCount.ShouldBe(1);
+    }
+
+    [Fact]
+    public void From_ReprocessedJob_InvocationCountReflectsJobValue()
+    {
+        var job = CompletedJob();
+        job.InvocationCount = 3;
+
+        var response = JobResponse.From(job, Options());
+
+        response.InvocationCount.ShouldBe(3);
+    }
+
     // -------------------------------------------------------------------------
     // FulfilledServices field
     // -------------------------------------------------------------------------

src/TextServices.Tests/BuilderApi/SnsJobNotifierTests.cs

@@ -15,7 +15,7 @@ public sealed class SnsJobNotifierTests
     private static JobCompletionNotification MakeNotification(
         string jobId = "my/job",
         JobStatus status = JobStatus.Completed) =>
-        new(jobId, status, DateTimeOffset.UtcNow, 10, 500, null);
+        new(jobId, status, DateTimeOffset.UtcNow, 10, 500, null, 1);
 
     // -------------------------------------------------------------------------
     // No-op when TopicArn is absent

src/TextServices.Tests/BuilderApi/TextBuildJobTests.cs

@@ -598,6 +598,32 @@ public async Task ExecuteAsync_OnSuccess_NotifiesWithCompletedStatus()
         notifier.Captured[0].Status.ShouldBe(JobStatus.Completed);
     }
 
+    [Fact]
+    public async Task ExecuteAsync_OnSuccess_NotificationCarriesInvocationCount()
+    {
+        var pages = new List<PageInstruction>
+        {
+            new() { Id = "https://example.org/c/1", Width = 1000, Height = 1500,
+                    TextUri = "https://example.org/alto/1.xml" },
+        };
+
+        var job = await CreateJob("test/notify-invocation-count",
+            sourceDataJson: JsonSerializer.Serialize(pages),
+            invocationCount: 2);
+
+        var altoFetcher = FakeAlto(new Dictionary<string, XElement>
+        {
+            ["https://example.org/alto/1.xml"] = SampleAlto("hello world"),
+        });
+
+        var notifier = new CapturingJobNotifier();
+        var sut = MakeJob(altoFetcher: altoFetcher, jobNotifier: notifier);
+        await sut.ExecuteAsync(job.Id, FakeCancellationToken.Instance);
+
+        notifier.Captured.ShouldHaveSingleItem();
+        notifier.Captured[0].InvocationCount.ShouldBe(2);
+    }
+
     [Fact]
     public async Task ExecuteAsync_OnFailure_NotifiesWithFailedStatus()
     {
@@ -622,14 +648,15 @@ public async Task ExecuteAsync_OnFailure_NotifiesWithFailedStatus()
 
     private async Task<BuilderJob> CreateJob(string id,
         string? sourceUri = null, string? sourceDataJson = null,
-        JobServices services = JobServices.All)
+        JobServices services = JobServices.All, int invocationCount = 1)
     {
         var job = new BuilderJob
         {
             Id = id,
             SourceUri = sourceUri,
             SourceDataJson = sourceDataJson,
             Services = (int)services,
+            InvocationCount = invocationCount,
         };
         _db.Jobs.Add(job);
         await _db.SaveChangesAsync();