feat(#78): one citizen reference across self-service and the openbaar register (#79)

## What & why

Before this change the self-service confirmation and the openbaar register showed **different** identifiers, so a citizen could not look their registration back up (#78). Now both surface the same **reference**:

- **domain → ACL (write):** the domain `registrationId` is set as the zaak's `identificatie` on `POST /zaken`.
- **event-subscriber → ACL (read):** the subscriber reads the zaak's `identificatie` back through the ACL (§8.1 — only the ACL talks to ZGW) via a new `POST /zaken/reference`, and stores it on the projection row **and** the `processed_notifications` replay log.
- **BFF + openbaar:** the public view exposes `id/status/reference` (never bsn/naam) and searches by id or reference; the register's "Referentie" column shows the reference.

Storing the reference in the replay log keeps ADR-0008's **rebuild-is-log-only** invariant intact — `/admin/rebuild` reproduces the reference without re-reading the ACL.

Decision recorded in **ADR-0012**.

## Definition of Done

- [x] Linked issue: #78
- [x] Tests written first; red → green per layer
- [x] Unit + acceptance green (`make unit`): domain 49, acl 27, bff 20, event-subscriber 19, acceptance 7
- [x] Frontend lint + test green (`nx run-many -t lint test`)
- [x] Mutation ≥ break(90): acl 100%, event-subscriber 100%, bff 100%, domain 98.41% (pre-existing FlowableWorkflowClient baseline, untouched)
- [x] e2e extended: confirmation reference == register reference
- [x] openapi.json + api-client regenerated (drift guard green)
- [x] ADR-0012 added; demo-script note appended
- [x] `Acl__BaseUrl` wired for the subscriber in compose

closes #78

Reviewed-on: #79

services/projection-api/Projection.ReadModel/EfNotificationLog.cs

@@ -16,6 +16,7 @@ public sealed class EfNotificationLog(ProjectionDbContext db) : INotificationLog
             Actie = notification.Actie,
             ZaakId = notification.ZaakId,
             Resource = notification.Resource,
+            Reference = notification.Reference,
             ReceivedAt = DateTimeOffset.UtcNow,
         });
 
@@ -35,6 +36,6 @@ public sealed class EfNotificationLog(ProjectionDbContext db) : INotificationLog
     public async Task<IReadOnlyList<RecordedNotification>> AllAsync(CancellationToken ct = default)
         => await db.ProcessedNotifications
             .OrderBy(r => r.ReceivedAt)
-            .Select(r => new RecordedNotification(r.Key, r.Actie, r.ZaakId, r.Resource))
+            .Select(r => new RecordedNotification(r.Key, r.Actie, r.ZaakId, r.Resource, r.Reference))
             .ToListAsync(ct);
 }

services/projection-api/Projection.ReadModel/EfProjectionStore.cs

@@ -15,6 +15,7 @@ public sealed class EfProjectionStore(ProjectionDbContext db) : IProjectionStore
             {
                 Id = entry.Id,
                 Status = entry.Status,
+                Reference = entry.Reference,
                 Bsn = entry.Bsn,
                 NaamPlaceholder = entry.NaamPlaceholder,
             });
@@ -22,6 +23,7 @@ public sealed class EfProjectionStore(ProjectionDbContext db) : IProjectionStore
         else
         {
             row.Status = entry.Status;
+            row.Reference = entry.Reference;
             row.Bsn = entry.Bsn;
             row.NaamPlaceholder = entry.NaamPlaceholder;
         }
@@ -35,6 +37,6 @@ public sealed class EfProjectionStore(ProjectionDbContext db) : IProjectionStore
     public async Task<IReadOnlyList<RegisterEntry>> AllAsync(CancellationToken ct = default)
         => await db.RegisterEntries
             .OrderBy(r => r.Id)
-            .Select(r => new RegisterEntry(r.Id, r.Status, r.Bsn, r.NaamPlaceholder))
+            .Select(r => new RegisterEntry(r.Id, r.Status, Reference: r.Reference, Bsn: r.Bsn, NaamPlaceholder: r.NaamPlaceholder))
             .ToListAsync(ct);
 }

services/projection-api/Projection.ReadModel/Migrations/20260714101642_AddReferenceColumns.Designer.cs

@@ -0,0 +1,92 @@
+// <auto-generated />
+using System;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Infrastructure;
+using Microsoft.EntityFrameworkCore.Migrations;
+using Microsoft.EntityFrameworkCore.Storage.ValueConversion;
+using Npgsql.EntityFrameworkCore.PostgreSQL.Metadata;
+using Projection.ReadModel;
+
+#nullable disable
+
+namespace Projection.ReadModel.Migrations
+{
+    [DbContext(typeof(ProjectionDbContext))]
+    [Migration("20260714101642_AddReferenceColumns")]
+    partial class AddReferenceColumns
+    {
+        /// <inheritdoc />
+        protected override void BuildTargetModel(ModelBuilder modelBuilder)
+        {
+#pragma warning disable 612, 618
+            modelBuilder
+                .HasAnnotation("ProductVersion", "10.0.0")
+                .HasAnnotation("Relational:MaxIdentifierLength", 63);
+
+            NpgsqlModelBuilderExtensions.UseIdentityByDefaultColumns(modelBuilder);
+
+            modelBuilder.Entity("Projection.ReadModel.ProcessedNotificationRow", b =>
+                {
+                    b.Property<string>("Key")
+                        .HasColumnType("text")
+                        .HasColumnName("key");
+
+                    b.Property<string>("Actie")
+                        .IsRequired()
+                        .HasColumnType("text")
+                        .HasColumnName("actie");
+
+                    b.Property<DateTimeOffset>("ReceivedAt")
+                        .HasColumnType("timestamp with time zone")
+                        .HasColumnName("received_at");
+
+                    b.Property<string>("Reference")
+                        .HasColumnType("text")
+                        .HasColumnName("reference");
+
+                    b.Property<string>("Resource")
+                        .IsRequired()
+                        .HasColumnType("text")
+                        .HasColumnName("resource");
+
+                    b.Property<string>("ZaakId")
+                        .IsRequired()
+                        .HasColumnType("text")
+                        .HasColumnName("zaak_id");
+
+                    b.HasKey("Key");
+
+                    b.ToTable("processed_notifications", (string)null);
+                });
+
+            modelBuilder.Entity("Projection.ReadModel.RegisterEntryRow", b =>
+                {
+                    b.Property<string>("Id")
+                        .HasColumnType("text")
+                        .HasColumnName("id");
+
+                    b.Property<string>("Bsn")
+                        .HasColumnType("text")
+                        .HasColumnName("bsn");
+
+                    b.Property<string>("NaamPlaceholder")
+                        .HasColumnType("text")
+                        .HasColumnName("naam_placeholder");
+
+                    b.Property<string>("Reference")
+                        .HasColumnType("text")
+                        .HasColumnName("reference");
+
+                    b.Property<string>("Status")
+                        .IsRequired()
+                        .HasColumnType("text")
+                        .HasColumnName("status");
+
+                    b.HasKey("Id");
+
+                    b.ToTable("register_projection", (string)null);
+                });
+#pragma warning restore 612, 618
+        }
+    }
+}

services/projection-api/Projection.ReadModel/Migrations/20260714101642_AddReferenceColumns.cs

@@ -0,0 +1,38 @@
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace Projection.ReadModel.Migrations
+{
+    /// <inheritdoc />
+    public partial class AddReferenceColumns : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.AddColumn<string>(
+                name: "reference",
+                table: "register_projection",
+                type: "text",
+                nullable: true);
+
+            migrationBuilder.AddColumn<string>(
+                name: "reference",
+                table: "processed_notifications",
+                type: "text",
+                nullable: true);
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropColumn(
+                name: "reference",
+                table: "register_projection");
+
+            migrationBuilder.DropColumn(
+                name: "reference",
+                table: "processed_notifications");
+        }
+    }
+}

services/projection-api/Projection.ReadModel/Migrations/ProjectionDbContextModelSnapshot.cs

@@ -37,6 +37,10 @@ namespace Projection.ReadModel.Migrations
                         .HasColumnType("timestamp with time zone")
                         .HasColumnName("received_at");
 
+                    b.Property<string>("Reference")
+                        .HasColumnType("text")
+                        .HasColumnName("reference");
+
                     b.Property<string>("Resource")
                         .IsRequired()
                         .HasColumnType("text")
@@ -66,6 +70,10 @@ namespace Projection.ReadModel.Migrations
                         .HasColumnType("text")
                         .HasColumnName("naam_placeholder");
 
+                    b.Property<string>("Reference")
+                        .HasColumnType("text")
+                        .HasColumnName("reference");
+
                     b.Property<string>("Status")
                         .IsRequired()
                         .HasColumnType("text")

services/projection-api/Projection.ReadModel/ProjectionDbContext.cs

@@ -24,6 +24,7 @@ public sealed class ProjectionDbContext(DbContextOptions<ProjectionDbContext> op
             e.HasKey(r => r.Id);
             e.Property(r => r.Id).HasColumnName("id");
             e.Property(r => r.Status).HasColumnName("status").IsRequired();
+            e.Property(r => r.Reference).HasColumnName("reference");
             e.Property(r => r.Bsn).HasColumnName("bsn");
             e.Property(r => r.NaamPlaceholder).HasColumnName("naam_placeholder");
         });
@@ -36,6 +37,7 @@ public sealed class ProjectionDbContext(DbContextOptions<ProjectionDbContext> op
             e.Property(r => r.Actie).HasColumnName("actie").IsRequired();
             e.Property(r => r.ZaakId).HasColumnName("zaak_id").IsRequired();
             e.Property(r => r.Resource).HasColumnName("resource").IsRequired();
+            e.Property(r => r.Reference).HasColumnName("reference");
             e.Property(r => r.ReceivedAt).HasColumnName("received_at");
         });
     }
@@ -46,6 +48,10 @@ public sealed class RegisterEntryRow
 {
     public required string Id { get; set; }
     public required string Status { get; set; }
+
+    /// <summary>The citizen-facing reference (the zaak's identificatie) — matches the submit confirmation (#78).</summary>
+    public string? Reference { get; set; }
+
     public string? Bsn { get; set; }
     public string? NaamPlaceholder { get; set; }
 }
@@ -61,5 +67,8 @@ public sealed class ProcessedNotificationRow
     /// the right status without reading OpenZaak (S-09b).</summary>
     public required string Resource { get; set; }
 
+    /// <summary>The zaak reference (identificatie), retained so a rebuild reprojects it without the ACL (#78).</summary>
+    public string? Reference { get; set; }
+
     public DateTimeOffset ReceivedAt { get; set; }
 }

services/projection-api/ProjectionApi.Api/Program.cs

@@ -23,7 +23,7 @@ app.MapGet("/register", async (ProjectionDbContext db, CancellationToken ct) =>
 {
     var rows = await db.RegisterEntries
         .OrderBy(r => r.Id)
-        .Select(r => new RegisterEntryDto(r.Id, r.Status, r.Bsn, r.NaamPlaceholder))
+        .Select(r => new RegisterEntryDto(r.Id, r.Status, r.Reference, r.Bsn, r.NaamPlaceholder))
         .ToListAsync(ct);
     return Results.Ok(rows);
 });
@@ -32,13 +32,13 @@ app.MapGet("/register/{id}", async (string id, ProjectionDbContext db, Cancellat
 {
     var row = await db.RegisterEntries
         .Where(r => r.Id == id)
-        .Select(r => new RegisterEntryDto(r.Id, r.Status, r.Bsn, r.NaamPlaceholder))
+        .Select(r => new RegisterEntryDto(r.Id, r.Status, r.Reference, r.Bsn, r.NaamPlaceholder))
         .SingleOrDefaultAsync(ct);
     return row is null ? Results.NotFound() : Results.Ok(row);
 });
 
 await app.RunAsync();
 
-public sealed record RegisterEntryDto(string Id, string Status, string? Bsn, string? NaamPlaceholder);
+public sealed record RegisterEntryDto(string Id, string Status, string? Reference, string? Bsn, string? NaamPlaceholder);
 
 public partial class Program;