register-referentie/docs/architecture/adr-0017-document-wait-timeout-cancellation.md

# ADR-0017: A document-wait task with a 30-day interrupting timer cancels the registration

- **Status:** Accepted
- **Date:** 2026-07-20
- **Deciders:** Respellion engineering
- **Relates to:** S-10a (#102); proposal #104; split from S-10 (#11). Builds on ADR-0009 (external-task
  worker / Workflow Client), ADR-0014 (withdrawal cancels the process), ADR-0015 (beoordeling
  escalation — the boundary-timer + external-worker pattern), ADR-0016 (diploma-eligibility DMN).

## Context

Flow 2 (PRD §5) requires the citizen to supply documents (their diploma) after submitting. The
registratie process must park waiting for those documents and, if they do not arrive within 30 days,
cancel the case. S-10 was split (§13): **S-10a** is this workflow/timeout spine (backend only);
**S-10b** wires the actual upload (portal → BFF → domain → ACL → Documenten API) that completes the
wait. This ADR records the spine: where the wait sits, how the timeout cancels, and how the domain
aggregate stays in sync.

## Decision

**A `WachtOpDocumenten` user task is inserted immediately after `OpenZaakAanmaken`, carrying an
`cancelActivity="true"` (interrupting) `P30D` boundary timer. "Documents received" completes the task
and the process continues into the diploma-eligibility routing; on timeout the timer cancels the task,
runs a `RegistratieVerlopen` external-worker task, and ends the process at `endVerlopen`. A domain
worker expires the correlated aggregate to a new terminal status `Verlopen`.**

- **Where the wait sits.** Right after the zaak is opened, before the diploma-eligibility DMN: the zaak
  exists, then the process waits for documents; on receipt it continues to the DMN routing → Beoordelen
  (ADR-0016). The wait gates the whole assessment, so it precedes the routing rather than sitting
  between the gateway and Beoordelen.
- **Interrupting timer, mirroring the existing constructs.** Unlike the S-14 escalation timer
  (non-interrupting — the Beoordelen task stays open), this timer is interrupting: when it fires the
  wait token is consumed and the case is cancelled, like the S-11 withdrawal boundary (ADR-0014). The
  timeout branch runs a `RegistratieVerlopen` external-worker task (topic mirrors
  `OpenZaakAanmaken`/`BeoordelingEscaleren`) → `endVerlopen`.
- **The domain stays authoritative.** The `RegistratieVerlopen` job carries the `registrationId`; the
  `RegistratieVerlopenProcessor` drains it and the `ExpireRegistrationWorker` loads the aggregate and
  calls `Registration.Expire()`, moving it to the new terminal status `Verlopen`. This keeps the
  aggregate — which the projection/openbaar view reads — the source of truth, exactly as escalation and
  withdrawal do. Idempotent per §8.6: a redelivered job whose aggregate is already `Verlopen` completes
  without persisting again; an unknown registration throws so the job is redelivered.
- **Documents-in-time transition.** `IWorkflowClient.CompleteDocumentWaitAsync(processInstanceId)`
  completes the `WachtOpDocumenten` task (the Workflow Client remains the only code that talks to
  Flowable, §8.2). It is best-effort — a no-op if the instance already left the wait (continued, or
  timed out). The *trigger* that calls it (the portal upload) is wired in S-10b; S-10a builds and tests
  the completion path with the trigger stubbed (the live check completes the task directly to prove the
  in-time branch, and the domain acceptance drives the worker against an in-memory stand-in).

## Consequences

**Positive**

- The wait/timeout is a first-class workflow construct that reuses the boundary-timer + external-worker
  pattern already proven by S-14, so the domain change is small and additive: one terminal status, one
  worker trio (worker + processor + pump), one Workflow Client method.
- §8 stays clean: the Workflow Client is still the only Flowable caller, and no new ZGW boundary is
  introduced in S-10a.
- The timeout is verified live (verify-domain fires the P30D timer via the management-API "move" idiom
  and asserts the domain reaches `Verlopen`), consistent with ADR-0009/0014/0015.

**Negative / costs**

- Every registration now parks at `WachtOpDocumenten` before Beoordelen, so the other live-check blocks
  (S-11/S-12b/S-13/S-14) must complete that task first — a small, explicit step standing in for the
  S-10b upload until it lands.
- On expiry S-10a cancels the *process* and marks the aggregate `Verlopen` but does **not** set the ZGW
  *zaak* to a cancellation status — that needs a new ACL method + statustype seeding, which overlaps
  S-10b's ACL/infra work. Deferred to S-10b (or a follow-up); noted here as the S-10a/S-10b boundary.

## Alternatives considered

- **Pure-BPMN cancellation (timer → end event, no worker).** Rejected: the domain aggregate would then
  be out of sync with the cancelled process, and the openbaar/projection view reads the aggregate's
  status — the case would still look open.
- **Wait task between the gateway and Beoordelen.** Rejected: documents gate the whole assessment
  (including the CBGV-advies routing), so the wait belongs before the DMN, not after it.
- **A dedicated timeout status per branch vs. reusing an open-state guard.** `Expire()` reuses the same
  `RequireOpenForDecision` guard as withdrawal/decision, so only an `INGEDIEND`/`IN_BEHANDELING`
  registration can lapse and the terminal states stay mutually exclusive — no new guard logic.