feat(workflow): diploma-eligibility DMN routes foreign diplomas via CBGV-advies (S-13, closes #14) (#101)

## What & why

S-13: a diploma's origin decides its route. A **DMN** (`diploma-eligibility`) is evaluated inline by
the registratie process as a **`businessRuleTask`**; an exclusive gateway routes a **foreign**
(Buitenlands) diploma through a new **CBGVAdvies** user task before `Beoordelen`, a **domestic** one
straight there (PRD flow 4). The domain's only new job is carrying the diploma origin and passing it
as a process start variable.

Chose **Option B (DMN in the BPMN)** over the issue's literal "evaluated by the Domain Service via
Workflow Client" wording — keeps the decision a first-class workflow artefact and §8.2 clean.
Rationale in **ADR-0016** (proposal #100); noted on this issue.

Closes #14

## Definition of Done

- [x] Linked Gitea issue (above).
- [x] Failing test committed before the implementation.
- [x] Implementation makes the test pass.
- [x] Conventional Commits referencing the issue (`refs #14`).
- [ ] CI green — all Gitea Actions jobs.
- [x] `docker compose up` from a fresh clone reaches green health checks within 3 minutes (additive; DMN deployed by flowable-init).
- [x] Docs updated (ADR-0016, demo note).
- [x] ADR added (`docs/architecture/adr-0016-diploma-eligibility-dmn.md`).
- [x] Demo note in `docs/demo-script.md`.

## How it was built (TDD)

- **Domain**: `DiplomaOrigin` on the aggregate + submit command; threaded through the process-start port so the Workflow Client emits a `diplomaOrigin` start variable. Red → green.
- **DMN + BPMN**: `workflows/diploma-eligibility.dmn` (origin → route); `businessRuleTask` + exclusive gateway + `CBGVAdvies` user task in `registratie.bpmn`; DMN deployed to Flowable's DMN engine by `flowable-init`.
- **Both paths**: `Een diploma op herkomst routeren` acceptance scenarios (origin carried into the process) + unit tests; verify-domain drives a foreign registration through CBGVAdvies→Beoordelen and the domestic one straight to Beoordelen — exercising both DMN branches live.

## Notes for reviewers

- Deviation from the issue's Option-A wording is deliberate and recorded (ADR-0016); the outcome is unchanged.
- The self-service eIDAS→foreign wiring is out of scope here (this slice is area:domain + area:workflow); the domain submit accepts an optional `diplomaOrigin` so the foreign path is drivable.
- Local green: domain unit 109, acceptance 15, `dotnet format`, Release build (0 errors), **domain mutation 95.39%** (break 90). The DMN/`businessRuleTask` REST wiring is CI-verified on verify-stack (no local full-stack run here).

Reviewed-on: #101

services/domain/Big.Api/Program.cs

@@ -48,7 +48,12 @@ app.MapGet("/health", () => "Healthy");
 // a location to read the registration's progress (ADR-0009, eventual consistency).
 app.MapPost("/registrations", async (SubmitRegistrationRequest body, SubmitRegistration submit, CancellationToken ct) =>
 {
-    var id = await submit.HandleAsync(new SubmitRegistrationCommand(body.Bsn), ct);
+    // Diploma origin defaults to domestic; a foreign (eIDAS) submission passes "Buitenlands" so the
+    // workflow's DMN routes it through CBGV-advies (S-13). An unknown value is a bad request.
+    if (!Enum.TryParse<DiplomaOrigin>(body.DiplomaOrigin, ignoreCase: true, out var origin) && body.DiplomaOrigin is not null)
+        return Results.BadRequest(new { error = $"Unknown diplomaOrigin '{body.DiplomaOrigin}'. Expected 'Binnenlands' or 'Buitenlands'." });
+
+    var id = await submit.HandleAsync(new SubmitRegistrationCommand(body.Bsn, origin), ct);
     return Results.Accepted($"/registrations/{id}", new RegistrationResponse(id.ToString(), RegistrationStatus.Ingediend.ToString(), null));
 });
 
@@ -117,7 +122,7 @@ app.MapGet("/registrations/{id}", async (string id, IRegistrationStore store, Ca
 
 await app.RunAsync();
 
-public sealed record SubmitRegistrationRequest(string Bsn);
+public sealed record SubmitRegistrationRequest(string Bsn, string? DiplomaOrigin = null);
 
 public sealed record DecideRequest(string Besluit);
 

services/domain/Big.Application/Ports.cs

@@ -11,10 +11,12 @@ public interface IWorkflowClient
 {
     /// <summary>
     /// Start one <c>registratie</c> process instance for the given registration, carrying the
-    /// registration id so the <c>OpenZaakAanmaken</c> external task can be correlated back to its
-    /// aggregate. Returns the process instance id.
+    /// registration id (so the <c>OpenZaakAanmaken</c> external task can be correlated back to its
+    /// aggregate) and the diploma origin (so the workflow's DMN can route foreign diplomas through
+    /// CBGV-advies, S-13). Returns the process instance id.
     /// </summary>
-    Task<string> StartRegistrationProcessAsync(RegistrationId registrationId, CancellationToken ct = default);
+    Task<string> StartRegistrationProcessAsync(
+        RegistrationId registrationId, DiplomaOrigin diplomaOrigin, CancellationToken ct = default);
 
     /// <summary>
     /// Cancel a running <c>registratie</c> process on withdrawal (S-11): correlate the

services/domain/Big.Application/SubmitRegistration.cs

@@ -2,8 +2,10 @@ using Big.Domain;
 
 namespace Big.Application;
 
-/// <summary>A zorgprofessional's request to register, in domain language. No ZGW concepts.</summary>
-public sealed record SubmitRegistrationCommand(string Bsn);
+/// <summary>A zorgprofessional's request to register, in domain language. No ZGW concepts. The
+/// diploma origin defaults to domestic (the DigiD path); a foreign (eIDAS) submission sets it to
+/// <see cref="DiplomaOrigin.Buitenlands"/> so the workflow's DMN routes it through CBGV-advies (S-13).</summary>
+public sealed record SubmitRegistrationCommand(string Bsn, DiplomaOrigin DiplomaOrigin = DiplomaOrigin.Binnenlands);
 
 /// <summary>
 /// The submit use case: create the <see cref="Registration"/> aggregate (INGEDIEND), persist it,
@@ -18,13 +20,14 @@ public sealed class SubmitRegistration(IRegistrationStore store, IWorkflowClient
     {
         ArgumentNullException.ThrowIfNull(command);
 
-        var registration = Registration.Submit(command.Bsn);
+        var registration = Registration.Submit(command.Bsn, command.DiplomaOrigin);
 
         // Persist before starting the process so the worker can correlate the OpenZaakAanmaken
         // job back to an aggregate that already exists (ADR-0009).
         await store.SaveAsync(registration, ct);
 
-        var processInstanceId = await workflow.StartRegistrationProcessAsync(registration.Id, ct);
+        var processInstanceId = await workflow.StartRegistrationProcessAsync(
+            registration.Id, registration.DiplomaOrigin, ct);
         registration.RecordProcessStarted(processInstanceId);
         await store.SaveAsync(registration, ct);
 

services/domain/Big.Domain/DiplomaOrigin.cs

@@ -0,0 +1,17 @@
+namespace Big.Domain;
+
+/// <summary>
+/// Where a zorgprofessional's diploma was issued. It is the input to the diploma-eligibility decision
+/// (S-13): a <see cref="Buitenlands"/> (foreign) diploma routes the registratie through an extra
+/// CBGV-advies assessment step, a <see cref="Binnenlands"/> (domestic) one goes straight to beoordeling.
+/// The decision itself lives in the workflow's DMN, not here (ADR-0016); the domain only carries the
+/// origin and hands it to the process as a start variable.
+/// </summary>
+public enum DiplomaOrigin
+{
+    /// <summary>A Dutch (domestic) diploma. Default for a registration submitted via DigiD.</summary>
+    Binnenlands,
+
+    /// <summary>A foreign diploma (e.g. an eIDAS submission). Triggers the CBGV-advies step.</summary>
+    Buitenlands,
+}

services/domain/Big.Domain/Registration.cs

@@ -7,10 +7,11 @@ namespace Big.Domain;
 /// </summary>
 public sealed class Registration
 {
-    private Registration(RegistrationId id, string bsn)
+    private Registration(RegistrationId id, string bsn, DiplomaOrigin diplomaOrigin)
     {
         Id = id;
         Bsn = bsn;
+        DiplomaOrigin = diplomaOrigin;
         Status = RegistrationStatus.Ingediend;
     }
 
@@ -20,6 +21,10 @@ public sealed class Registration
     /// as the domain payload; the domain never constructs ZGW concepts from it (§8.1).</summary>
     public string Bsn { get; }
 
+    /// <summary>Where the diploma was issued. Rides along to the process as a start variable and
+    /// drives the diploma-eligibility DMN's foreign→CBGV-advies routing (S-13, ADR-0016).</summary>
+    public DiplomaOrigin DiplomaOrigin { get; }
+
     public RegistrationStatus Status { get; private set; }
 
     /// <summary>The Flowable process instance driving this registration, once started.</summary>
@@ -28,11 +33,13 @@ public sealed class Registration
     /// <summary>The zaak the ACL opened for this registration, once the external task has run.</summary>
     public Uri? ZaakUrl { get; private set; }
 
-    /// <summary>Submit a new registration. It begins in <see cref="RegistrationStatus.Ingediend"/>.</summary>
-    public static Registration Submit(string bsn)
+    /// <summary>Submit a new registration. It begins in <see cref="RegistrationStatus.Ingediend"/>.
+    /// The diploma origin defaults to <see cref="DiplomaOrigin.Binnenlands"/> — the common DigiD path;
+    /// a foreign (eIDAS) submission passes <see cref="DiplomaOrigin.Buitenlands"/>.</summary>
+    public static Registration Submit(string bsn, DiplomaOrigin diplomaOrigin = DiplomaOrigin.Binnenlands)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(bsn);
-        return new Registration(RegistrationId.New(), bsn);
+        return new Registration(RegistrationId.New(), bsn, diplomaOrigin);
     }
 
     /// <summary>Record that the registratie workflow process has been started for this registration.</summary>

services/domain/Big.Infrastructure/FlowableWorkflowClient.cs

@@ -24,15 +24,20 @@ public sealed class FlowableWorkflowClient(HttpClient http, FlowableOptions opti
     private const string BehandelaarGroup = "behandelaar";
     private const string TeamleadGroup = "teamlead";
     private const string RegistrationIdVariable = "registrationId";
+    private const string DiplomaOriginVariable = "diplomaOrigin";
     private const string ZaakUrlVariable = "zaakUrl";
     private const string BesluitVariable = "besluit";
     private const string IngetrokkenMessage = "RegistratieIngetrokken";
 
-    public async Task<string> StartRegistrationProcessAsync(RegistrationId registrationId, CancellationToken ct = default)
+    public async Task<string> StartRegistrationProcessAsync(
+        RegistrationId registrationId, DiplomaOrigin diplomaOrigin, CancellationToken ct = default)
     {
         var request = new StartProcessRequest(
             ProcessDefinitionKey,
-            [new Variable(RegistrationIdVariable, "string", registrationId.ToString())]);
+            [
+                new Variable(RegistrationIdVariable, "string", registrationId.ToString()),
+                new Variable(DiplomaOriginVariable, "string", diplomaOrigin.ToString()),
+            ]);
 
         var created = await PostAsync<StartProcessRequest, ProcessInstance>(
             "service/runtime/process-instances", request, ct)

services/domain/Big.Tests/Fakes.cs

@@ -32,12 +32,15 @@ internal sealed class FakeWorkflowClient(string processInstanceId = "proc-1", Ac
     : IWorkflowClient
 {
     public RegistrationId? StartedFor { get; private set; }
+    public DiplomaOrigin? StartedWithOrigin { get; private set; }
     public string? WithdrawnProcessInstanceId { get; private set; }
 
-    public Task<string> StartRegistrationProcessAsync(RegistrationId registrationId, CancellationToken ct = default)
+    public Task<string> StartRegistrationProcessAsync(
+        RegistrationId registrationId, DiplomaOrigin diplomaOrigin, CancellationToken ct = default)
     {
         onStart?.Invoke(registrationId);
         StartedFor = registrationId;
+        StartedWithOrigin = diplomaOrigin;
         return Task.FromResult(processInstanceId);
     }
 

services/domain/Big.Tests/FlowableWorkflowClientTests.cs

@@ -24,7 +24,7 @@ public class FlowableWorkflowClientTests
         var client = Client(capture.Responds(HttpStatusCode.Created, """{"id":"pi-1"}"""));
         var rid = RegistrationId.New();
 
-        var pid = await client.StartRegistrationProcessAsync(rid);
+        var pid = await client.StartRegistrationProcessAsync(rid, DiplomaOrigin.Binnenlands);
 
         Assert.Equal("pi-1", pid);
         Assert.Equal(HttpMethod.Post, capture.Seen!.Method);
@@ -38,6 +38,22 @@ public class FlowableWorkflowClientTests
         Assert.Contains($"\"value\":\"{rid}\"", capture.Body);
     }
 
+    [Theory]
+    [InlineData(DiplomaOrigin.Binnenlands, "Binnenlands")]
+    [InlineData(DiplomaOrigin.Buitenlands, "Buitenlands")]
+    public async Task Start_posts_the_diploma_origin_as_a_process_variable(DiplomaOrigin origin, string expected)
+    {
+        // The diploma origin rides along as a start variable so the workflow's DMN can route foreign
+        // diplomas through CBGV-advies (S-13, ADR-0016).
+        var capture = new RequestCapture();
+        var client = Client(capture.Responds(HttpStatusCode.Created, """{"id":"pi-1"}"""));
+
+        await client.StartRegistrationProcessAsync(RegistrationId.New(), origin);
+
+        Assert.Contains("\"name\":\"diplomaOrigin\"", capture.Body);
+        Assert.Contains($"\"value\":\"{expected}\"", capture.Body);
+    }
+
     [Fact]
     public async Task Start_uses_the_configured_worker_credentials_and_defaults()
     {
@@ -125,7 +141,7 @@ public class FlowableWorkflowClientTests
         var client = Client(capture.Responds(HttpStatusCode.InternalServerError));
 
         await Assert.ThrowsAsync<HttpRequestException>(
-            () => client.StartRegistrationProcessAsync(RegistrationId.New()));
+            () => client.StartRegistrationProcessAsync(RegistrationId.New(), DiplomaOrigin.Binnenlands));
     }
 
     [Fact]
@@ -135,7 +151,7 @@ public class FlowableWorkflowClientTests
         var client = Client(capture.Responds(HttpStatusCode.Created, "null"));
 
         var ex = await Assert.ThrowsAsync<InvalidOperationException>(
-            () => client.StartRegistrationProcessAsync(RegistrationId.New()));
+            () => client.StartRegistrationProcessAsync(RegistrationId.New(), DiplomaOrigin.Binnenlands));
         Assert.Contains("empty process-instance", ex.Message);
     }
 

services/domain/Big.Tests/RegistrationTests.cs

@@ -16,6 +16,15 @@ public class RegistrationTests
         Assert.Null(registration.ProcessInstanceId);
     }
 
+    [Fact]
+    public void A_registration_defaults_to_a_domestic_diploma()
+        => Assert.Equal(DiplomaOrigin.Binnenlands, Registration.Submit("123456782").DiplomaOrigin);
+
+    [Fact]
+    public void A_foreign_diploma_submission_records_its_origin()
+        => Assert.Equal(DiplomaOrigin.Buitenlands,
+            Registration.Submit("123456782", DiplomaOrigin.Buitenlands).DiplomaOrigin);
+
     [Theory]
     [InlineData("")]
     [InlineData("   ")]

services/domain/Big.Tests/SubmitRegistrationTests.cs

@@ -25,6 +25,19 @@ public class SubmitRegistrationTests
         Assert.Equal(2, store.SaveCount);
     }
 
+    [Fact]
+    public async Task Submitting_a_foreign_diploma_carries_its_origin_to_the_process()
+    {
+        var store = new FakeRegistrationStore();
+        var workflow = new FakeWorkflowClient();
+        var handler = new SubmitRegistration(store, workflow);
+
+        var id = await handler.HandleAsync(new SubmitRegistrationCommand("123456782", DiplomaOrigin.Buitenlands));
+
+        Assert.Equal(DiplomaOrigin.Buitenlands, (await store.GetAsync(id))!.DiplomaOrigin);
+        Assert.Equal(DiplomaOrigin.Buitenlands, workflow.StartedWithOrigin);
+    }
+
     [Fact]
     public async Task Rejects_a_null_command_without_touching_the_store_or_workflow()
     {