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/bff/Bff.Api/DownstreamClients.cs

@@ -6,11 +6,12 @@ namespace Bff.Api;
 public sealed record SubmitAccepted(string RegistrationId, string Status);
 
 /// <summary>A projection row as the projection-api serves it. <c>Bsn</c>/<c>NaamPlaceholder</c> are
-/// read but never surfaced by the openbaar endpoint (public-safe filtering, ADR-0010/S-09).</summary>
-public sealed record ProjectionEntry(string Id, string Status, string? Bsn, string? NaamPlaceholder);
+/// read but never surfaced by the openbaar endpoint (public-safe filtering, ADR-0010/S-09).
+/// <c>Reference</c> is the public-safe citizen reference (the zaak identificatie, #78).</summary>
+public sealed record ProjectionEntry(string Id, string Status, string? Reference, string? Bsn, string? NaamPlaceholder);
 
 /// <summary>A public-safe openbaar register row — only non-sensitive fields leave the BFF.</summary>
-public sealed record OpenbaarEntry(string Id, string Status);
+public sealed record OpenbaarEntry(string Id, string Status, string? Reference);
 
 /// <summary>Port to the Domain Service (§8.3: the BFF is the portals' only backend; it fans out).</summary>
 public interface IDomainClient

services/bff/Bff.Api/OpenbaarProjection.cs

@@ -11,8 +11,10 @@ public static class OpenbaarProjection
     {
         var filtered = string.IsNullOrWhiteSpace(q)
             ? entries
-            : entries.Where(e => e.Id.Contains(q, StringComparison.OrdinalIgnoreCase));
+            : entries.Where(e =>
+                e.Id.Contains(q, StringComparison.OrdinalIgnoreCase) ||
+                (e.Reference?.Contains(q, StringComparison.OrdinalIgnoreCase) ?? false));
 
-        return [.. filtered.Select(e => new OpenbaarEntry(e.Id, e.Status))];
+        return [.. filtered.Select(e => new OpenbaarEntry(e.Id, e.Status, e.Reference))];
     }
 }

services/bff/Bff.Tests/OpenbaarEndpointTests.cs

@@ -10,7 +10,7 @@ public class OpenbaarEndpointTests
     public async Task Serves_public_safe_rows_anonymously()
     {
         using var factory = new BffFactory();
-        factory.Projection.Entries.Add(new ProjectionEntry("abc-111", "INGEDIEND", "123456782", "Jan"));
+        factory.Projection.Entries.Add(new ProjectionEntry("abc-111", "INGEDIEND", "REG-abc", "123456782", "Jan"));
 
         // No Authorization header — the openbaar register is a public lookup (ADR-0010/S-09).
         var response = await factory.CreateClient().GetAsync("/openbaar/register");
@@ -19,7 +19,9 @@ public class OpenbaarEndpointTests
         var body = await response.Content.ReadAsStringAsync();
         Assert.Contains("abc-111", body);
         Assert.Contains("INGEDIEND", body);
-        // The bsn must never appear in a public response.
+        // The public reference is surfaced (matches the submit confirmation, #78)...
+        Assert.Contains("REG-abc", body);
+        // ...but the bsn must never appear in a public response.
         Assert.DoesNotContain("123456782", body);
     }
 
@@ -27,8 +29,8 @@ public class OpenbaarEndpointTests
     public async Task Filters_by_the_query_parameter()
     {
         using var factory = new BffFactory();
-        factory.Projection.Entries.Add(new ProjectionEntry("abc-111", "INGEDIEND", null, null));
-        factory.Projection.Entries.Add(new ProjectionEntry("def-222", "INGEDIEND", null, null));
+        factory.Projection.Entries.Add(new ProjectionEntry("abc-111", "INGEDIEND", "REG-abc", null, null));
+        factory.Projection.Entries.Add(new ProjectionEntry("def-222", "INGEDIEND", "REG-def", null, null));
 
         var rows = await factory.CreateClient()
             .GetFromJsonAsync<List<OpenbaarEntry>>("/openbaar/register?q=abc");

services/bff/Bff.Tests/OpenbaarProjectionTests.cs

@@ -6,8 +6,8 @@ public class OpenbaarProjectionTests
 {
     private static readonly ProjectionEntry[] Sample =
     [
-        new("abc-111", "INGEDIEND", "123456782", "Jan"),
-        new("def-222", "INGEDIEND", "987654321", "Piet"),
+        new("abc-111", "INGEDIEND", Reference: "REG-A", Bsn: "123456782", NaamPlaceholder: "Jan"),
+        new("def-222", "INGESCHREVEN", Reference: "REG-B", Bsn: "987654321", NaamPlaceholder: "Piet"),
     ];
 
     [Fact]
@@ -18,31 +18,47 @@ public class OpenbaarProjectionTests
         Assert.Equal(2, view.Count);
         Assert.Equal("abc-111", view[0].Id);
         Assert.Equal("INGEDIEND", view[0].Status);
+        // The public reference (zaak identificatie) is surfaced so it matches the submit confirmation (#78).
+        Assert.Equal("REG-A", view[0].Reference);
     }
 
     [Fact]
-    public void Public_view_exposes_only_id_and_status()
+    public void Public_view_exposes_only_id_status_and_reference()
     {
-        // OpenbaarEntry structurally carries only Id + Status — bsn/naam can never leak.
+        // OpenbaarEntry structurally carries only public-safe fields — bsn/naam can never leak.
         var props = typeof(OpenbaarEntry).GetProperties().Select(p => p.Name).ToArray();
-        Assert.Equal(["Id", "Status"], props);
+        Assert.Equal(["Id", "Status", "Reference"], props);
     }
 
     [Theory]
-    [InlineData("abc", 1)]
-    [InlineData("ABC", 1)]
-    [InlineData("2", 1)]
-    [InlineData("zzz", 0)]
+    [InlineData("abc", 1)]   // by id
+    [InlineData("ABC", 1)]   // by id, case-insensitive
+    [InlineData("def", 1)]   // by id
+    [InlineData("zzz", 0)]   // no match
     public void Filters_by_id_containing_the_query_case_insensitively(string q, int expected)
-    {
-        var view = OpenbaarProjection.PublicView(Sample, q);
+        => Assert.Equal(expected, OpenbaarProjection.PublicView(Sample, q).Count);
 
-        Assert.Equal(expected, view.Count);
-    }
+    [Theory]
+    [InlineData("REG-A", 1)] // by reference — the citizen's confirmation reference
+    [InlineData("reg-a", 1)] // by reference, case-insensitive
+    [InlineData("REG", 2)]   // both share the prefix
+    public void Filters_by_reference_containing_the_query_case_insensitively(string q, int expected)
+        => Assert.Equal(expected, OpenbaarProjection.PublicView(Sample, q).Count);
 
     [Fact]
     public void Blank_query_is_treated_as_no_filter()
     {
         Assert.Equal(2, OpenbaarProjection.PublicView(Sample, "   ").Count);
     }
+
+    [Fact]
+    public void A_row_without_a_reference_never_matches_a_query()
+    {
+        // Older rows can have a null reference (the column is additive, #78/ADR-0012). A search must
+        // simply not match them — it must not throw and must not treat "no reference" as a match.
+        var entries = new[] { new ProjectionEntry("xyz-999", "INGEDIEND", Reference: null, Bsn: null, NaamPlaceholder: null) };
+
+        Assert.Empty(OpenbaarProjection.PublicView(entries, "REG"));
+        Assert.Equal("xyz-999", Assert.Single(OpenbaarProjection.PublicView(entries, "xyz")).Id);
+    }
 }

services/bff/openapi.json

@@ -67,7 +67,8 @@
       "OpenbaarEntry": {
         "required": [
           "id",
-          "status"
+          "status",
+          "reference"
         ],
         "type": "object",
         "properties": {
@@ -76,6 +77,12 @@
           },
           "status": {
             "type": "string"
+          },
+          "reference": {
+            "type": [
+              "null",
+              "string"
+            ]
           }
         }
       },
@@ -101,4 +108,4 @@
       "name": "Bff.Api"
     }
   ]
-}
+}