fix(infra): deploy diploma-eligibility DMN via dmn-api, not a process .bar (refs #14)

flowable-rest does not cascade a .dmn bundled inside a process .bar into the
DMN engine: the resource is stored but no decision is created, so the DMN
service task fails at runtime with FlowableObjectNotFoundException. Deploy the
DMN to the DMN engine via /dmn-api/dmn-repository/deployments and the BPMN to
the process engine separately; the service task resolves the decision across
deployments by key (verified live: Buitenlands->CBGV_ADVIES, Binnenlands->DIRECT).

Also move the DMN's doc comment inside <definitions>: Flowable's DMN XML
converter rejects a comment between the <?xml?> declaration and the root element
(XMLStreamReader not in START_DOCUMENT/START_ELEMENT state), unlike its BPMN one.

seed-config.sh now seeds both raw workflow files instead of building a .bar.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/architecture/adr-0016-diploma-eligibility-dmn.md

@@ -1,4 +1,4 @@
-# ADR-0016: Diploma eligibility is a DMN evaluated inline as a BPMN businessRuleTask
+# ADR-0016: Diploma eligibility is a DMN evaluated inline as a BPMN DMN service task
 
 - **Status:** Accepted
 - **Date:** 2026-07-17
@@ -22,21 +22,32 @@ back. That is one option; it is not the only one, and it is not the cleanest.
 ## Decision
 
 **The diploma-eligibility DMN is deployed to Flowable and evaluated inline by the registratie process
-as a `businessRuleTask`; an exclusive gateway routes on its output. The domain's only new job is to
-carry the diploma origin and pass it into the process as a start variable.**
+as a DMN service task (`flowable:type="dmn"`); an exclusive gateway routes on its output. The domain's
+only new job is to carry the diploma origin and pass it into the process as a start variable.**
 
 - **The decision lives in the workflow.** `workflows/diploma-eligibility.dmn` maps `diplomaOrigin`
-  → `route` (`Buitenlands` ⇒ `CBGV_ADVIES`, otherwise `DIRECT`). A `businessRuleTask`
+  → `route` (`Buitenlands` ⇒ `CBGV_ADVIES`, otherwise `DIRECT`). A DMN service task
   (`flowable:type="dmn"`, `decisionTableReferenceKey=diploma-eligibility`) runs it between
   `OpenZaakAanmaken` and `Beoordelen`, and an exclusive gateway sends `CBGV_ADVIES` through a new
-  `CBGVAdvies` user task before `Beoordelen`, `DIRECT` straight there.
+  `CBGVAdvies` user task before `Beoordelen`, `DIRECT` straight there. (A `businessRuleTask` would
+  bind Flowable's legacy Drools/KIE implementation, which `flowable-rest` does not bundle — its parse
+  handler throws `NoClassDefFoundError` at deploy time; the DMN service task is the supported route.)
 - **The domain carries the input, not the decision.** The `Registration` aggregate gains a
   `DiplomaOrigin` (Binnenlands/Buitenlands); `SubmitRegistration` passes it to
   `StartRegistrationProcessAsync`, which sets it as the `diplomaOrigin` start variable. The domain
   never evaluates the DMN and never learns the route — that is the process's concern.
-- **Deployed like the BPMN.** The DMN is version-controlled in `workflows/` and deployed to the DMN
-  engine by the same `flowable-init` step (via `dmn-api/dmn-repository/deployments`), staged into the
-  `fl-bpmn` volume alongside the BPMN.
+- **Deployed as its own DMN-engine deployment, separate from the BPMN.** The DMN is version-controlled
+  in `workflows/` and `flowable-init` deploys it to the DMN engine via the `dmn-api`
+  (`/dmn-api/dmn-repository/deployments`), while `registratie.bpmn` goes to the process engine via
+  `/service/repository/deployments`. Two things were learned the hard way here (both cost a CI cycle):
+  (1) `flowable-rest` does **not** cascade a `.dmn` bundled inside a process `.bar` into the DMN engine
+  — the resource is stored but no decision is created, so the service task fails at runtime with
+  `FlowableObjectNotFoundException: No decision found for key`; the DMN must go through `dmn-api`.
+  (2) Flowable's DMN XML converter rejects an XML comment placed between the `<?xml?>` declaration and
+  the root `<definitions>` element (`XMLStreamReader not in START_DOCUMENT or START_ELEMENT state`),
+  unlike its BPMN converter — so the DMN's documentation comment lives *inside* `<definitions>`.
+  With the decision present in the DMN repository, the process's DMN service task resolves it across
+  deployments by key (verified live), so no shared parent deployment id is needed.
 
 ## Consequences
 
@@ -52,7 +63,7 @@ carry the diploma origin and pass it into the process as a start variable.**
 
 - Deviates from #14's literal "evaluated by the Domain Service via Workflow Client" wording (noted on
   the issue). The outcome — DMN decides eligibility, foreign diplomas get the CBGV step — is unchanged.
-- The DMN and its `businessRuleTask` wiring are validated live (verify-domain drives a foreign
+- The DMN and its service-task wiring are validated live (verify-domain drives a foreign
   registration through CBGV-advies and a domestic one straight to beoordeling, exercising both
   branches), not in unit tests — consistent with ADR-0009/0014/0015. The domain unit/acceptance tests
   cover only that the origin is carried into the process.

docs/demo-script.md

@@ -346,7 +346,7 @@ candidate group behandelaar → teamlead (§8.2).
 
 ## S-13 — Diploma-eligibility: foreign diplomas route through CBGV-advies (#14, ADR-0016)
 
-A registration's diploma origin decides its route. A DMN `businessRuleTask` in the registratie
+A registration's diploma origin decides its route. A DMN service task in the registratie
 process evaluates the `diploma-eligibility` decision on the `diplomaOrigin` start variable: a
 **foreign** (Buitenlands) diploma is routed through an extra **CBGV-advies** user task before
 beoordeling; a **domestic** (Binnenlands) one goes straight to beoordeling. The decision lives in the
@@ -376,7 +376,7 @@ curl -s -u rest-admin:test -X POST "$FL/runtime/tasks/$TID" \
 ```
 
 **The path:** domain sets the `diplomaOrigin` start variable → registratie process DMN
-`businessRuleTask` sets `route` → exclusive gateway → foreign: `CBGVAdvies` user task → `Beoordelen`;
+DMN service task sets `route` → exclusive gateway → foreign: `CBGVAdvies` user task → `Beoordelen`;
 domestic: `Beoordelen` directly (§8.2, ADR-0016).
 
 > The domestic/foreign paths are covered by the `Een diploma op herkomst routeren` acceptance

infra/docker-compose.yml

@@ -259,27 +259,30 @@ services:
   flowable-init:
     image: docker.io/curlimages/curl:latest
     restart: "no"
-    # registratie.bpmn + diploma-eligibility.dmn are 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
-        dmnbase=http://flowable-rest:8080/flowable-rest/dmn-api/dmn-repository/deployments
-        until curl -sf -u rest-admin:test "$$base" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
-        # Deploy the diploma-eligibility DMN to the DMN engine so the registratie process's
-        # businessRuleTask can resolve it by key (S-13, ADR-0016).
-        if curl -s -u rest-admin:test "$$dmnbase?name=diploma-eligibility" | grep -q '"name":"diploma-eligibility"'; then
-          echo "diploma-eligibility 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/diploma-eligibility.dmn;filename=diploma-eligibility.dmn' "$$dmnbase" >/dev/null && echo "deployed diploma-eligibility"
+          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 "$$base?name=registratie" | grep -q '"name":"registratie"'; then
-          echo "registratie already deployed; skip"
+        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' "$$base" >/dev/null && echo "deployed registratie"
+          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,32 +35,35 @@ services:
         condition: service_healthy
     networks: [cg]
 
-  # Deploys workflows/registratie.bpmn + diploma-eligibility.dmn via the REST API once flowable-rest is up.
-  # Idempotent: skips each if a deployment of that name 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 + diploma-eligibility.dmn are 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
-        dmnbase=http://flowable-rest:8080/flowable-rest/dmn-api/dmn-repository/deployments
-        until curl -sf -u rest-admin:test "$$base" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
-        # Deploy the diploma-eligibility DMN to the DMN engine so the registratie process's
-        # businessRuleTask can resolve it by key (S-13, ADR-0016).
-        if curl -s -u rest-admin:test "$$dmnbase?name=diploma-eligibility" | grep -q '"name":"diploma-eligibility"'; then
-          echo "diploma-eligibility 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/diploma-eligibility.dmn;filename=diploma-eligibility.dmn' "$$dmnbase" >/dev/null && echo "deployed diploma-eligibility"
+          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 "$$base?name=registratie" | grep -q '"name":"registratie"'; then
-          echo "registratie already deployed; skip"
+        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' "$$base" >/dev/null && echo "deployed registratie"
+          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

@@ -159,7 +159,7 @@ done
 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 businessRuleTask sets route=CBGV_ADVIES and 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}'

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 + diploma-eligibility.dmn
+    fl) d="$(mktemp -d)"; stage_flowable_workflows "$d"; populate rr-fl-bpmn "$d/." ;;
     *)  echo "unknown seed key: $key" >&2; exit 2 ;;
   esac
 done

workflows/diploma-eligibility.dmn

@@ -1,14 +1,17 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!-- Diploma-eligibility decision (S-13, ADR-0016). Evaluated inline by the registratie process as a
-     BPMN businessRuleTask: given the diploma's origin, it sets the `route` the process should take.
-     A foreign (Buitenlands) diploma routes through the extra CBGV-advies assessment step; a domestic
-     one (or anything else) goes DIRECT to beoordeling. FIRST hit policy: the foreign rule wins, and
-     the empty-input catch-all is the default. -->
 <definitions xmlns="https://www.omg.org/spec/DMN/20191111/MODEL/"
              xmlns:flowable="http://flowable.org/dmn"
              id="diplomaEligibilityDefinitions"
              name="Diploma eligibility"
              namespace="http://respellion.nl/big/dmn">
+  <!-- Diploma-eligibility decision (S-13, ADR-0016). Evaluated inline by the registratie process as a
+       BPMN DMN service task: given the diploma's origin, it sets the `route` the process should take.
+       A foreign (Buitenlands) diploma routes through the extra CBGV-advies assessment step; a domestic
+       one (or anything else) goes DIRECT to beoordeling. FIRST hit policy: the foreign rule wins, and
+       the empty-input catch-all is the default.
+       NB: the comment lives INSIDE <definitions> on purpose — Flowable's DMN XML converter chokes on a
+       comment between the XML declaration and the root element ("XMLStreamReader not in START_DOCUMENT
+       or START_ELEMENT state"), unlike its BPMN converter. -->
   <decision id="diploma-eligibility" name="Diploma eligibility">
     <decisionTable id="dt-diploma-eligibility" hitPolicy="FIRST">
       <input id="in-origin" label="Diploma origin">

workflows/registratie.bpmn

@@ -22,9 +22,9 @@
        (BeoordelingEscaleren); the Workflow Client reassigns the still-open Beoordelen task from the
        behandelaar group to teamlead (ADR-0015). The Beoordelen task stays open throughout — the timer
        only changes who may claim it.
-       S-13 adds diploma-eligibility routing: between OpenZaakAanmaken and Beoordelen a DMN
-       businessRuleTask evaluates the `diploma-eligibility` decision on the diplomaOrigin start
-       variable; an exclusive gateway routes a foreign diploma through the CBGV-advies user task
+       S-13 adds diploma-eligibility routing: between OpenZaakAanmaken and Beoordelen a DMN service
+       task (flowable:type="dmn") evaluates the `diploma-eligibility` decision on the diplomaOrigin
+       start variable; an exclusive gateway routes a foreign diploma through the CBGV-advies user task
        before Beoordelen, a domestic one straight there (ADR-0016). -->
   <message id="Message_Ingetrokken" name="RegistratieIngetrokken"/>
 
@@ -40,17 +40,19 @@
 
     <sequenceFlow id="flow2" sourceRef="OpenZaakAanmaken" targetRef="DiplomaEligibiliteit"/>
 
-    <!-- S-13: evaluate the diploma-eligibility DMN inline (ADR-0016). Flowable runs the deployed
-         `diploma-eligibility` decision against the diplomaOrigin start variable and sets the `route`
-         output as a process variable. The gateway then routes a foreign diploma through CBGV-advies,
-         a domestic one straight to Beoordelen. -->
-    <businessRuleTask id="DiplomaEligibiliteit" name="Diploma-eligibiliteit bepalen" flowable:type="dmn">
+    <!-- S-13: evaluate the diploma-eligibility DMN inline (ADR-0016). A Flowable DMN service task
+         (flowable:type="dmn" — NOT a businessRuleTask, whose default implementation is the legacy
+         Drools/KIE one that flowable-rest does not bundle) runs the deployed `diploma-eligibility`
+         decision against the diplomaOrigin start variable and sets the `route` output as a process
+         variable. The gateway then routes a foreign diploma through CBGV-advies, a domestic one
+         straight to Beoordelen. -->
+    <serviceTask id="DiplomaEligibiliteit" name="Diploma-eligibiliteit bepalen" flowable:type="dmn">
       <extensionElements>
         <flowable:field name="decisionTableReferenceKey">
           <flowable:string><![CDATA[diploma-eligibility]]></flowable:string>
         </flowable:field>
       </extensionElements>
-    </businessRuleTask>
+    </serviceTask>
 
     <sequenceFlow id="flow2a" sourceRef="DiplomaEligibiliteit" targetRef="RouteOpDiploma"/>