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

infra/docker-compose.yml

@@ -259,19 +259,30 @@ services:
   flowable-init:
     image: docker.io/curlimages/curl:latest
     restart: "no"
-    # registratie.bpmn is streamed into this external volume by infra/seed-config.sh.
+    # registratie.bpmn + diploma-eligibility.dmn are streamed into this external volume by
+    # infra/seed-config.sh.
     volumes:
       - fl-bpmn:/work:ro
     command:
       - sh
       - -c
       - |
-        base=http://flowable-rest:8080/flowable-rest/service/repository/deployments
-        until curl -sf -u rest-admin:test "$$base" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
-        if curl -s -u rest-admin:test "$$base?name=registratie" | grep -q '"name":"registratie"'; then
-          echo "registratie already deployed; skip"
+        svc=http://flowable-rest:8080/flowable-rest/service/repository/deployments
+        dmn=http://flowable-rest:8080/flowable-rest/dmn-api/dmn-repository/deployments
+        until curl -sf -u rest-admin:test "$$svc" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
+        # Deploy the DMN to the DMN engine and the BPMN to the process engine as SEPARATE deployments:
+        # flowable-rest does NOT cascade a .dmn bundled in a process .bar into the DMN engine, so the DMN
+        # must go via dmn-api. The process's DMN service task then resolves the decision across deployments
+        # by key (S-13, ADR-0016). Both steps are idempotent (skip if already deployed).
+        if curl -s -u rest-admin:test "$$dmn" | grep -q '"name":"diploma-eligibility.dmn"'; then
+          echo "diploma-eligibility DMN already deployed; skip"
         else
-          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bpmn;filename=registratie.bpmn' "$$base" >/dev/null && echo "deployed registratie"
+          curl -sf -u rest-admin:test -F 'file=@/work/diploma-eligibility.dmn;filename=diploma-eligibility.dmn' "$$dmn" >/dev/null && echo "deployed diploma-eligibility DMN"
+        fi
+        if curl -s -u rest-admin:test "$$svc?name=registratie" | grep -q '"name":"registratie"'; then
+          echo "registratie BPMN already deployed; skip"
+        else
+          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bpmn;filename=registratie.bpmn' "$$svc" >/dev/null && echo "deployed registratie BPMN"
         fi
     depends_on:
       flowable-rest:

infra/flowable/docker-compose.yml

@@ -35,24 +35,35 @@ services:
         condition: service_healthy
     networks: [cg]
 
-  # Deploys workflows/registratie.bpmn via the REST API once flowable-rest is up.
-  # Idempotent: skips if a deployment named "registratie" already exists.
+  # Deploys registratie.bpmn (process engine) and diploma-eligibility.dmn (DMN engine) via the REST
+  # API once flowable-rest is up. Idempotent: skips each if already deployed.
   flowable-init:
     image: docker.io/curlimages/curl:latest
     restart: "no"
-    # registratie.bpmn is streamed into this external volume by infra/seed-config.sh.
+    # registratie.bpmn + diploma-eligibility.dmn are streamed into this external volume by
+    # infra/seed-config.sh.
     volumes:
       - fl-bpmn:/work:ro
     command:
       - sh
       - -c
       - |
-        base=http://flowable-rest:8080/flowable-rest/service/repository/deployments
-        until curl -sf -u rest-admin:test "$$base" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
-        if curl -s -u rest-admin:test "$$base?name=registratie" | grep -q '"name":"registratie"'; then
-          echo "registratie already deployed; skip"
+        svc=http://flowable-rest:8080/flowable-rest/service/repository/deployments
+        dmn=http://flowable-rest:8080/flowable-rest/dmn-api/dmn-repository/deployments
+        until curl -sf -u rest-admin:test "$$svc" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
+        # Deploy the DMN to the DMN engine and the BPMN to the process engine as SEPARATE deployments:
+        # flowable-rest does NOT cascade a .dmn bundled in a process .bar into the DMN engine, so the DMN
+        # must go via dmn-api. The process's DMN service task then resolves the decision across deployments
+        # by key (S-13, ADR-0016). Both steps are idempotent (skip if already deployed).
+        if curl -s -u rest-admin:test "$$dmn" | grep -q '"name":"diploma-eligibility.dmn"'; then
+          echo "diploma-eligibility DMN already deployed; skip"
         else
-          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bpmn;filename=registratie.bpmn' "$$base" >/dev/null && echo "deployed registratie"
+          curl -sf -u rest-admin:test -F 'file=@/work/diploma-eligibility.dmn;filename=diploma-eligibility.dmn' "$$dmn" >/dev/null && echo "deployed diploma-eligibility DMN"
+        fi
+        if curl -s -u rest-admin:test "$$svc?name=registratie" | grep -q '"name":"registratie"'; then
+          echo "registratie BPMN already deployed; skip"
+        else
+          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bpmn;filename=registratie.bpmn' "$$svc" >/dev/null && echo "deployed registratie BPMN"
         fi
     depends_on:
       flowable-rest:

infra/run-domain-check.sh

@@ -158,6 +158,49 @@ done
 [ -n "$gone" ] || { echo "FAIL — Beoordelen task for $reg_id2 still active after withdrawal" >&2; docker logs "$dom" 2>&1 | tail -15 >&2; exit 1; }
 echo "OK — withdrawal cancelled the Beoordelen task; the registratie process ended (ingetrokken)"
 
+# ── S-13: diploma-eligibility routing. A registration with a FOREIGN diploma must route through the
+# extra CBGVAdvies user task before Beoordelen (the DMN service task sets route=CBGV_ADVIES and the
+# gateway branches, ADR-0016). The domestic DIRECT path is already proven by the first registration
+# above, which parked straight at Beoordelen. ──────────────────────────────────────────────────────
+cbgv_query='{"processDefinitionKey":"registratie","taskDefinitionKey":"CBGVAdvies","includeProcessVariables":true}'
+echo ">> submitting a registration with a foreign diploma"
+locf="$(docker run --rm --network "$net" curlimages/curl:latest \
+  -fsS -D - -o /dev/null -X POST "http://$dom_ip:8080/registrations" \
+  -H 'Content-Type: application/json' -d '{"bsn":"123456782","diplomaOrigin":"Buitenlands"}' \
+  | sed -n 's/\r$//; s/^[Ll]ocation: //p' | head -1)"
+[ -n "$locf" ] || { echo "FAIL — foreign POST /registrations returned no Location" >&2; exit 1; }
+reg_idf="${locf##*/}"
+echo ">> foreign registration $reg_idf"
+
+echo ">> polling Flowable for its CBGV-advies task (foreign diplomas route here first)"
+cbgv_task=""
+for _ in $(seq 1 30); do
+  resp="$(flcurl -X POST "$fl_base/query/tasks" -H 'Content-Type: application/json' -d "$cbgv_query" 2>/dev/null || true)"
+  cbgv_task="$(printf '%s' "$resp" | task_for_reg "$reg_idf")"
+  [ -n "$cbgv_task" ] && break
+  sleep 2
+done
+[ -n "$cbgv_task" ] || { echo "FAIL — no CBGVAdvies task appeared for the foreign registration $reg_idf" >&2; docker logs "$dom" 2>&1 | tail -15 >&2; exit 1; }
+echo ">> CBGVAdvies task $cbgv_task is waiting"
+
+echo ">> asserting it has NOT reached Beoordelen yet (still awaiting CBGV-advies)"
+resp="$(flcurl -X POST "$fl_base/query/tasks" -H 'Content-Type: application/json' -d "$query")"
+early="$(printf '%s' "$resp" | task_for_reg "$reg_idf")"
+[ -z "$early" ] || { echo "FAIL — foreign registration reached Beoordelen ($early) before CBGV-advies" >&2; exit 1; }
+
+echo ">> completing the CBGV-advies task"
+flcurl -X POST "$fl_base/runtime/tasks/$cbgv_task" -H 'Content-Type: application/json' -d '{"action":"complete"}' >/dev/null
+
+echo ">> asserting it now advances to Beoordelen"
+onward=""
+for _ in $(seq 1 15); do
+  resp="$(flcurl -X POST "$fl_base/query/tasks" -H 'Content-Type: application/json' -d "$query" 2>/dev/null || true)"
+  [ -n "$(printf '%s' "$resp" | task_for_reg "$reg_idf")" ] && { onward=1; break; }
+  sleep 2
+done
+[ -n "$onward" ] || { echo "FAIL — foreign registration did not reach Beoordelen after CBGV-advies" >&2; exit 1; }
+echo "OK — foreign diploma routed through CBGV-advies, then on to Beoordelen (DMN + gateway)"
+
 # ── S-14: escalation. A third registration parks at Beoordelen. We fire its 14-day boundary timer
 # early via Flowable's management API (the timer job is moved to executable and run), which routes a
 # parallel token to the BeoordelingEscaleren external task. The domain's escalation worker acquires

infra/seed-config.sh

@@ -35,12 +35,21 @@ populate() {  # volume  source(file or dir/.)
 
 [ "$#" -gt 0 ] || { echo "usage: seed-config.sh <oz|nrc|kc|fl> ..." >&2; exit 2; }
 
+# The registratie process (BPMN) and its diploma-eligibility DMN are deployed as SEPARATE Flowable
+# deployments — the process engine and the DMN engine each own theirs (S-13, ADR-0016). flowable-rest
+# does not cascade a .dmn bundled in a process .bar into the DMN engine, so we seed both raw files and
+# let flowable-init deploy each via its own REST app. We stage them in a temp dir and copy its contents.
+stage_flowable_workflows() {
+  local dir="$1"
+  cp "$here/../workflows/registratie.bpmn" "$here/../workflows/diploma-eligibility.dmn" "$dir/"
+}
+
 for key in "$@"; do
   case "$key" in
     oz) populate rr-oz-config "$here/openzaak/setup_configuration/." ;;
     nrc) populate rr-nrc-config "$here/opennotificaties/setup_configuration/." ;;
     kc) populate rr-kc-realms "$here/keycloak/realms/." ;;
-    fl) populate rr-fl-bpmn  "$here/../workflows/registratie.bpmn" ;;
+    fl) d="$(mktemp -d)"; stage_flowable_workflows "$d"; populate rr-fl-bpmn "$d/." ;;
     *)  echo "unknown seed key: $key" >&2; exit 2 ;;
   esac
 done