feat(fp): WP-21 — resilience seams (correlation-id, idempotency, retry)

Correlation id becomes real ASP.NET Core middleware instead of a per-endpoint
read: every request gets one (client-supplied or generated), it's echoed as
an X-Correlation-Id response header, and pushed into the logging scope so
every log line for that request carries it — not just the Submit helper's,
verified against LogBrief which never threads it explicitly.

Idempotency-Key moves from per-HTTP-attempt (defeating its own purpose) to
per-logical-submit: runSubmit mints one key and threads it through a small
bridge (withIdempotencyKey/currentIdempotencyKey) since the NSwag-generated
client has no per-call header hook. Backend gains an IdempotencyStore that
short-circuits a replayed key to the first call's result instead of minting
a second reference — scoped to the Submit-helper endpoints per the WP's own
decision.

GET requests now retry transient failures (rxjs retry({count:2, delay:500}));
writes never auto-retry. Proven with a fake-HttpClient spec
(api-client.provider.spec.ts) rather than a manual network-tab check — the
WP's suggested `?scenario=error` check turned out not to exercise a real
network call at all (the interceptor throws before calling next()), so the
automated test is the actual proof.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

backend/src/BigRegister.Api/Program.cs

@@ -8,6 +8,7 @@ using BigRegister.Domain.Documents;
 using BigRegister.Domain.Intake;
 using BigRegister.Domain.Registrations;
 using BigRegister.Domain.Submissions;
+using Microsoft.Extensions.Logging.Console;
 
 var builder = WebApplication.CreateBuilder(args);
 
@@ -20,6 +21,9 @@ builder.Services.ConfigureHttpJsonOptions(o =>
   o.SerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
   o.SerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
 });
+// So the correlation-id scope pushed by the middleware below actually shows up in
+// the console, not just in memory for a formatter that never renders it.
+builder.Logging.AddSimpleConsole(o => o.IncludeScopes = true);
 
 const string SpaCors = "spa";
 builder.Services.AddCors(o => o.AddPolicy(SpaCors, p =>
@@ -27,6 +31,21 @@ builder.Services.AddCors(o => o.AddPolicy(SpaCors, p =>
 
 var app = builder.Build();
 
+// Every request gets a correlation id (client-supplied X-Correlation-Id if present,
+// else generated), pushed into the logging scope for every log line the request
+// produces (not just the Submit helper's) and echoed back as a response header for
+// support/debugging correlation. Runs first so nothing downstream logs without it.
+app.Use(async (ctx, next) =>
+{
+  var cid = ctx.Request.Headers.TryGetValue("X-Correlation-Id", out var v) && !string.IsNullOrEmpty(v)
+      ? v.ToString()
+      : Guid.NewGuid().ToString();
+  ctx.Items["CorrelationId"] = cid;
+  ctx.Response.Headers["X-Correlation-Id"] = cid;
+  using (app.Logger.BeginScope("CorrelationId:{CorrelationId}", cid))
+    await next(ctx);
+});
+
 app.UseSwagger();
 app.UseSwaggerUI();
 app.UseCors(SpaCors);
@@ -345,33 +364,48 @@ void LogBrief(string action, (BriefStore.Outcome outcome, BriefEntity? entity) r
 
 // Audit + outcome for a submit, with NO personal data: only kind, outcome,
 // generated reference and the caller's correlation id (the observability seam — a
-// real system ships this to structured logging / an audit store).
+// real system ships this to structured logging / an audit store). A repeated
+// Idempotency-Key short-circuits to the first call's result — see IdempotencyStore
+// — so a retried submit dedupes instead of minting a second reference.
 IResult Submit(HttpContext ctx, string kind, string? reject, IReadOnlyList<DocumentRefDto>? documents = null)
 {
-  var cid = ctx.Request.Headers.TryGetValue("X-Correlation-Id", out var v) && !string.IsNullOrEmpty(v)
-      ? v.ToString()
-      : "none";
+  var cid = ctx.Items.TryGetValue("CorrelationId", out var v) ? (string)v! : "none";
+  var idemKey = ctx.Request.Headers.TryGetValue("Idempotency-Key", out var k) && !string.IsNullOrEmpty(k)
+      ? k.ToString()
+      : null;
 
+  if (idemKey is not null && IdempotencyStore.TryGet(idemKey, out var cached))
+  {
+    app.Logger.LogInformation("submit kind={Kind} outcome=replayed correlationId={Cid}", kind, cid);
+    return cached!;
+  }
+
+  IResult result;
   if (reject is not null)
   {
     app.Logger.LogInformation("submit kind={Kind} outcome=rejected correlationId={Cid}", kind, cid);
-    return Results.Problem(detail: reject, statusCode: StatusCodes.Status422UnprocessableEntity);
+    result = Results.Problem(detail: reject, statusCode: StatusCodes.Status422UnprocessableEntity);
   }
-
-  if (documents is not null)
+  else
   {
-    // Link digital documents (blocks later user delete) and record post-delivery
-    // intent so a caseworker knows to expect the physical document.
-    DocumentStore.Link(documents.Where(d => d.Channel == "digital" && d.DocumentId is not null).Select(d => d.DocumentId!));
-    foreach (var d in documents.Where(d => d.Channel == "post"))
-      DocumentStore.Audit("post-delivery", d.DocumentId ?? "-", d.CategoryId, cid);
+    if (documents is not null)
+    {
+      // Link digital documents (blocks later user delete) and record post-delivery
+      // intent so a caseworker knows to expect the physical document.
+      DocumentStore.Link(documents.Where(d => d.Channel == "digital" && d.DocumentId is not null).Select(d => d.DocumentId!));
+      foreach (var d in documents.Where(d => d.Channel == "post"))
+        DocumentStore.Audit("post-delivery", d.DocumentId ?? "-", d.CategoryId, cid);
+    }
+
+    var reference = SubmissionRules.NewReference();
+    app.Logger.LogInformation(
+        "submit kind={Kind} outcome=accepted reference={Reference} correlationId={Cid} at={At:o}",
+        kind, reference, cid, DateTimeOffset.UtcNow);
+    result = Results.Ok(new ReferentieResponse(reference));
   }
 
-  var reference = SubmissionRules.NewReference();
-  app.Logger.LogInformation(
-      "submit kind={Kind} outcome=accepted reference={Reference} correlationId={Cid} at={At:o}",
-      kind, reference, cid, DateTimeOffset.UtcNow);
-  return Results.Ok(new ReferentieResponse(reference));
+  if (idemKey is not null) IdempotencyStore.Set(idemKey, result);
+  return result;
 }
 
 // Exposed so the integration tests can spin up the app with WebApplicationFactory.