feat(workflow): document-wait task + 30-day timeout cancellation (S-10a, closes #102) (#105)

## What & why

S-10a, the **workflow/timeout spine** of the (split) document-upload slice: the registratie process
now parks at a **`WachtOpDocumenten`** user task with an **interrupting `P30D` boundary timer**. When
the documents arrive the task completes and the process continues into the diploma routing (S-13) →
Beoordelen; if the 30 days lapse, the timer cancels the wait, runs a `RegistratieVerlopen`
external-worker task, and the domain expires the aggregate to a new terminal status **`Verlopen`**.
Backend only — the real upload trigger (portal → BFF → ACL → Documenten API) is S-10b (#103).

Closes #102

Mechanism recorded in **ADR-0017**; opened as proposal #104. Mirrors the S-14 escalation
(boundary-timer + external-worker) and S-11 withdrawal (interrupting cancel) patterns.

## Definition of Done

- [x] Linked Gitea issue (above).
- [x] Failing test committed before the implementation (red→green pairs per layer).
- [x] Implementation makes the test pass.
- [x] Conventional Commits referencing the issue (`refs #102`).
- [ ] CI green — all Gitea Actions jobs (pending on this PR).
- [x] `docker compose up` health unaffected (no new services; deploy path unchanged).
- [x] Docs updated (ADR-0017, demo-script, BACKLOG split).
- [x] ADR added (`docs/architecture/adr-0017-document-wait-timeout-cancellation.md`).
- [x] Demo note in `docs/demo-script.md`.

## Notes for reviewers

- **Domain** (`Registration.Expire()` + `Verlopen`), **application** (`ExpireRegistrationWorker`),
  **infra** (`RegistratieVerlopenProcessor`/`Pump`, `IRegistratieVerlopenClient`, Flowable
  acquire/complete + `CompleteDocumentWaitAsync`) — the timeout counterpart to the OpenZaak/escalation
  worker trios; idempotent per §8.6.
- **BPMN** verified live against a `flowable-rest` probe: complete `WachtOpDocumenten` → routes to
  Beoordelen; fire the P30D timer → `RegistratieVerlopen` job (carrying `registrationId`) + the wait
  task cancelled. `verify-domain` exercises both branches in-stack (completes the wait in every existing
  block; fires the timer and asserts `Verlopen` in a new block).
- **Scope boundary:** on expiry the aggregate goes `Verlopen` and the process ends, but the ZGW *zaak*
  is not yet set to a cancellation status — that needs a new ACL method + statustype seeding and is
  folded into S-10b (noted in ADR-0017).
- `CompleteDocumentWaitAsync` is built and HTTP-tested here but not yet called from a domain endpoint;
  S-10b wires the upload trigger to it.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Reviewed-on: #105

infra/run-domain-check.sh

@@ -93,6 +93,27 @@ print(next((t['id'] for t in (d.get('data') or [])
 
 flcurl() { docker run --rm --network "$net" curlimages/curl:latest -fsS -u rest-admin:test "$@"; }
 query='{"processDefinitionKey":"registratie","taskDefinitionKey":"Beoordelen","includeProcessVariables":true}'
+wacht_query='{"processDefinitionKey":"registratie","taskDefinitionKey":"WachtOpDocumenten","includeProcessVariables":true}'
+
+# S-10a: every registration now parks at WachtOpDocumenten first (interrupting P30D timer). Completing
+# that task stands in for the citizen's document upload (wired for real in S-10b), letting the process
+# advance to the diploma routing / Beoordelen so the checks below still hold. The 30-day timeout branch
+# is exercised separately at the end.
+complete_wacht() {  # reg_id
+  local rid="$1" wid="" r
+  for _ in $(seq 1 30); do
+    r="$(flcurl -X POST "$fl_base/query/tasks" -H 'Content-Type: application/json' -d "$wacht_query" 2>/dev/null || true)"
+    wid="$(printf '%s' "$r" | task_for_reg "$rid")"
+    [ -n "$wid" ] && break
+    sleep 2
+  done
+  [ -n "$wid" ] || { echo "FAIL — no WachtOpDocumenten task appeared for $rid" >&2; docker logs "$dom" 2>&1 | tail -15 >&2; exit 1; }
+  flcurl -X POST "$fl_base/runtime/tasks/$wid" -H 'Content-Type: application/json' -d '{"action":"complete"}' >/dev/null
+  echo ">> completed WachtOpDocumenten for $rid (documents received)"
+}
+
+echo ">> completing WachtOpDocumenten so the process advances (documents received)"
+complete_wacht "$reg_id"
 
 echo ">> polling Flowable for the Beoordelen user task (werkbak)"
 task_id=""
@@ -130,6 +151,7 @@ loc2="$(docker run --rm --network "$net" curlimages/curl:latest \
 [ -n "$loc2" ] || { echo "FAIL — second POST /registrations returned no Location" >&2; exit 1; }
 reg_id2="${loc2##*/}"
 echo ">> second registration $reg_id2"
+complete_wacht "$reg_id2"
 
 echo ">> polling Flowable for its Beoordelen task"
 task_id2=""
@@ -171,6 +193,7 @@ locf="$(docker run --rm --network "$net" curlimages/curl:latest \
 [ -n "$locf" ] || { echo "FAIL — foreign POST /registrations returned no Location" >&2; exit 1; }
 reg_idf="${locf##*/}"
 echo ">> foreign registration $reg_idf"
+complete_wacht "$reg_idf"
 
 echo ">> polling Flowable for its CBGV-advies task (foreign diplomas route here first)"
 cbgv_task=""
@@ -241,6 +264,8 @@ except Exception:
     d={}
 print(((d.get('data') or [{}])[0]).get('id',''))"; }
 
+complete_wacht "$reg_id3"
+
 echo ">> polling Flowable for its Beoordelen task"
 task_id3=""; pid3=""
 for _ in $(seq 1 30); do
@@ -278,4 +303,50 @@ for _ in $(seq 1 30); do
 done
 [ -n "$escalated" ] || { echo "FAIL — Beoordelen task not reassigned to teamlead (candidate groups: '$groups')" >&2; docker logs "$dom" 2>&1 | tail -15 >&2; exit 1; }
 echo "OK — the 14-day timer escalated the still-open Beoordelen task to the teamlead"
+
+# ── S-10a: document timeout. A registration parks at WachtOpDocumenten and — unlike every block above —
+# its documents never arrive. We fire its 30-day boundary timer early via the management API; the
+# INTERRUPTING timer cancels the wait and routes a token to the RegistratieVerlopen external task. The
+# domain's timeout worker acquires it and expires the registration to VERLOPEN (ADR-0017). ────────────
+echo ">> submitting a registration to let its document term lapse"
+locv="$(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"}' \
+  | sed -n 's/\r$//; s/^[Ll]ocation: //p' | head -1)"
+[ -n "$locv" ] || { echo "FAIL — timeout POST /registrations returned no Location" >&2; exit 1; }
+reg_idv="${locv##*/}"
+echo ">> timeout registration $reg_idv"
+
+echo ">> polling Flowable for its WachtOpDocumenten task"
+wacht_id=""; pidv=""
+for _ in $(seq 1 30); do
+  resp="$(flcurl -X POST "$fl_base/query/tasks" -H 'Content-Type: application/json' -d "$wacht_query" 2>/dev/null || true)"
+  read -r wacht_id pidv <<<"$(printf '%s' "$resp" | task_and_pid_for_reg "$reg_idv")"
+  [ -n "$wacht_id" ] && break
+  sleep 2
+done
+[ -n "$wacht_id" ] || { echo "FAIL — no WachtOpDocumenten task appeared for $reg_idv" >&2; docker logs "$dom" 2>&1 | tail -15 >&2; exit 1; }
+echo ">> WachtOpDocumenten task $wacht_id (instance $pidv) is waiting for documents"
+
+echo ">> firing the 30-day document timer early via the management API"
+timer_idv="$(flcurl "$fl_base/management/timer-jobs?processInstanceId=$pidv" | first_job_id)"
+[ -n "$timer_idv" ] || { echo "FAIL — no timer job found for instance $pidv" >&2; exit 1; }
+# Move the timer job to an executable async job; the async executor fires the interrupting boundary
+# event. It may run before we look, so executing it explicitly is a best-effort nudge (as for S-14).
+flcurl -X POST "$fl_base/management/timer-jobs/$timer_idv" -H 'Content-Type: application/json' -d '{"action":"move"}' >/dev/null
+async_idv="$(flcurl "$fl_base/management/jobs?processInstanceId=$pidv" 2>/dev/null | first_job_id || true)"
+if [ -n "$async_idv" ]; then
+  flcurl -X POST "$fl_base/management/jobs/$async_idv" -H 'Content-Type: application/json' -d '{"action":"execute"}' >/dev/null 2>&1 || true
+fi
+echo ">> timer fired; the RegistratieVerlopen token is parked for the domain worker"
+
+echo ">> polling the domain until the timeout worker expires the registration to VERLOPEN"
+verlopen=""
+for _ in $(seq 1 30); do
+  body="$(docker run --rm --network "$net" curlimages/curl:latest -fsS "http://$dom_ip:8080$locv" 2>/dev/null || true)"
+  printf '%s' "$body" | grep -qi 'verlopen' && { verlopen=1; break; }
+  sleep 2
+done
+[ -n "$verlopen" ] || { echo "FAIL — registration $reg_idv not VERLOPEN after the document timer fired (body: $body)" >&2; docker logs "$dom" 2>&1 | tail -15 >&2; exit 1; }
+echo "OK — the 30-day document timer expired the registration to VERLOPEN"
 exit 0