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

services/domain/Big.Tests/ExpireRegistrationWorkerTests.cs

@@ -0,0 +1,84 @@
+using Big.Application;
+using Big.Domain;
+
+namespace Big.Tests;
+
+// S-10a (#102): the application handler behind the RegistratieVerlopen external-worker job. The 30-day
+// document-wait timer fired, so the correlated registration is expired to VERLOPEN. Mirrors
+// OpenZaakWorker — pure application logic over ports, idempotent under at-least-once delivery (§8.6).
+public class ExpireRegistrationWorkerTests
+{
+    private const string Bsn = "123456782";
+
+    private static Registration Submitted(string processInstanceId = "proc-1")
+    {
+        var registration = Registration.Submit(Bsn);
+        registration.RecordProcessStarted(processInstanceId);
+        return registration;
+    }
+
+    [Fact]
+    public async Task Expires_the_registration_the_job_correlates_to()
+    {
+        var store = new FakeRegistrationStore();
+        var registration = Submitted();
+        store.Seed(registration);
+
+        await new ExpireRegistrationWorker(store).HandleAsync(
+            new RegistratieVerlopenJob("job-7", registration.Id));
+
+        var saved = await store.GetAsync(registration.Id);
+        Assert.Equal(RegistrationStatus.Verlopen, saved!.Status);
+        Assert.Equal(1, store.SaveCount);
+    }
+
+    [Fact]
+    public async Task An_already_verlopen_registration_is_not_persisted_again()
+    {
+        // A redelivered job (§8.6) finds the aggregate already VERLOPEN: a no-op, not saved again.
+        var store = new FakeRegistrationStore();
+        var registration = Submitted();
+        registration.Expire();
+        store.Seed(registration);
+
+        await new ExpireRegistrationWorker(store).HandleAsync(
+            new RegistratieVerlopenJob("job-7", registration.Id));
+
+        Assert.Equal(0, store.SaveCount);
+        Assert.Equal(RegistrationStatus.Verlopen, (await store.GetAsync(registration.Id))!.Status);
+    }
+
+    [Fact]
+    public async Task An_already_resolved_registration_is_left_alone_and_the_job_completes()
+    {
+        // Race with S-11: the citizen withdrew while parked at WachtOpDocumenten, so the aggregate is
+        // already terminal (INGETROKKEN) when the timer's job arrives. Expiring it would violate the
+        // aggregate's invariant; the worker must instead no-op (and let the job complete), not throw
+        // into a redelivery loop.
+        var store = new FakeRegistrationStore();
+        var registration = Submitted();
+        registration.Withdraw();
+        store.Seed(registration);
+
+        await new ExpireRegistrationWorker(store).HandleAsync(
+            new RegistratieVerlopenJob("job-7", registration.Id));
+
+        Assert.Equal(0, store.SaveCount);
+        Assert.Equal(RegistrationStatus.Ingetrokken, (await store.GetAsync(registration.Id))!.Status);
+    }
+
+    [Fact]
+    public async Task An_unknown_registration_throws_so_the_job_is_redelivered()
+    {
+        var store = new FakeRegistrationStore();
+
+        await Assert.ThrowsAsync<InvalidOperationException>(() =>
+            new ExpireRegistrationWorker(store).HandleAsync(
+                new RegistratieVerlopenJob("job-7", RegistrationId.New())));
+    }
+
+    [Fact]
+    public async Task Rejects_a_null_job()
+        => await Assert.ThrowsAsync<ArgumentNullException>(() =>
+            new ExpireRegistrationWorker(new FakeRegistrationStore()).HandleAsync(null!));
+}

services/domain/Big.Tests/Fakes.cs

@@ -34,6 +34,7 @@ internal sealed class FakeWorkflowClient(string processInstanceId = "proc-1", Ac
     public RegistrationId? StartedFor { get; private set; }
     public DiplomaOrigin? StartedWithOrigin { get; private set; }
     public string? WithdrawnProcessInstanceId { get; private set; }
+    public string? CompletedDocumentWaitFor { get; private set; }
 
     public Task<string> StartRegistrationProcessAsync(
         RegistrationId registrationId, DiplomaOrigin diplomaOrigin, CancellationToken ct = default)
@@ -49,6 +50,12 @@ internal sealed class FakeWorkflowClient(string processInstanceId = "proc-1", Ac
         WithdrawnProcessInstanceId = processInstanceId;
         return Task.CompletedTask;
     }
+
+    public Task CompleteDocumentWaitAsync(string processInstanceId, CancellationToken ct = default)
+    {
+        CompletedDocumentWaitFor = processInstanceId;
+        return Task.CompletedTask;
+    }
 }
 
 /// <summary>A fake user-task client for the werkbak/decision use cases: returns a scripted set of

services/domain/Big.Tests/FlowableWorkflowClientTests.cs

@@ -426,4 +426,106 @@ public class FlowableWorkflowClientTests
             capture.Seen.RequestUri!.ToString());
         Assert.Contains("\"workerId\":\"worker-x\"", capture.Body);
     }
+
+    // ── S-10a (#102): document-wait timeout → RegistratieVerlopen (ADR-0017) ──────────────────────
+    // A 30-day interrupting boundary timer on WachtOpDocumenten spawns a RegistratieVerlopen
+    // external-worker job carrying the registration id; the worker expires the registration and
+    // completes the job. Separately, "documents received" completes the WachtOpDocumenten user task.
+
+    [Fact]
+    public async Task Acquire_verlopen_jobs_posts_the_topic_and_parses_jobs_with_their_registration_id()
+    {
+        var rid = RegistrationId.New();
+        var capture = new RequestCapture();
+        var client = Client(capture.Responds(HttpStatusCode.OK,
+            $$"""[{"id":"job-9","variables":[{"name":"registrationId","type":"string","value":"{{rid}}"}]}]"""));
+
+        var jobs = await client.AcquireRegistratieVerlopenJobsAsync(3);
+
+        var job = Assert.Single(jobs);
+        Assert.Equal("job-9", job.JobId);
+        Assert.Equal(rid, job.RegistrationId);
+        Assert.Equal("http://flowable/flowable-rest/external-job-api/acquire/jobs",
+            capture.Seen!.RequestUri!.ToString());
+        Assert.Contains("\"topic\":\"RegistratieVerlopen\"", capture.Body);
+        Assert.Contains("\"numberOfTasks\":3", capture.Body);
+        Assert.Contains("\"workerId\":\"worker-x\"", capture.Body);
+    }
+
+    [Theory]
+    [InlineData("[]")]
+    [InlineData("null")]
+    public async Task Acquire_verlopen_jobs_returns_empty_when_none_are_parked(string body)
+    {
+        var capture = new RequestCapture();
+        var client = Client(capture.Responds(HttpStatusCode.OK, body));
+
+        Assert.Empty(await client.AcquireRegistratieVerlopenJobsAsync(1));
+        Assert.NotNull(capture.Seen);
+    }
+
+    [Fact]
+    public async Task Complete_verlopen_job_posts_to_the_job_complete_endpoint()
+    {
+        var capture = new RequestCapture();
+        var client = Client(capture.Responds(HttpStatusCode.NoContent));
+
+        await client.CompleteRegistratieVerlopenJobAsync("job-9");
+
+        Assert.Equal(HttpMethod.Post, capture.Seen!.Method);
+        Assert.Equal("http://flowable/flowable-rest/external-job-api/acquire/jobs/job-9/complete",
+            capture.Seen.RequestUri!.ToString());
+        Assert.Contains("\"workerId\":\"worker-x\"", capture.Body);
+    }
+
+    [Fact]
+    public async Task Provide_documents_completes_the_wacht_op_documenten_task_in_the_instance()
+    {
+        var requests = new List<(HttpMethod Method, string Url, string? Body)>();
+        var client = Client(new StubHandler(async req =>
+        {
+            requests.Add((req.Method, req.RequestUri!.ToString(),
+                req.Content is null ? null : await req.Content.ReadAsStringAsync()));
+            return req.RequestUri!.AbsoluteUri.EndsWith("service/query/tasks")
+                ? new HttpResponseMessage(HttpStatusCode.OK)
+                {
+                    Content = new StringContent("""{"data":[{"id":"task-3"}],"total":1}""",
+                        Encoding.UTF8, "application/json"),
+                }
+                : new HttpResponseMessage(HttpStatusCode.OK);
+        }));
+
+        await client.CompleteDocumentWaitAsync("pi-1");
+
+        // 1. Find the still-open WachtOpDocumenten task in this process instance.
+        var query = requests.Single(r => r.Url.EndsWith("service/query/tasks"));
+        Assert.Equal(HttpMethod.Post, query.Method);
+        Assert.Contains("\"processInstanceId\":\"pi-1\"", query.Body);
+        Assert.Contains("\"taskDefinitionKey\":\"WachtOpDocumenten\"", query.Body);
+        // 2. Complete that task so the process leaves the wait state.
+        var complete = requests.Single(r => r.Url.EndsWith("service/runtime/tasks/task-3"));
+        Assert.Equal(HttpMethod.Post, complete.Method);
+        Assert.Contains("\"action\":\"complete\"", complete.Body);
+    }
+
+    [Fact]
+    public async Task Provide_documents_is_a_no_op_when_the_wait_task_is_no_longer_open()
+    {
+        // The process already left WachtOpDocumenten (e.g. timed out): nothing to complete, no throw.
+        var methods = new List<HttpMethod>();
+        var client = Client(new StubHandler(req =>
+        {
+            methods.Add(req.Method);
+            return Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent("""{"data":[],"total":0}""", Encoding.UTF8, "application/json"),
+            });
+        }));
+
+        await client.CompleteDocumentWaitAsync("pi-1");
+
+        // Only the query ran; no task-completion POST followed.
+        Assert.DoesNotContain(methods, m => m == HttpMethod.Put || m == HttpMethod.Delete);
+        Assert.Single(methods);
+    }
 }

services/domain/Big.Tests/ProvideDocumentsTests.cs

@@ -0,0 +1,85 @@
+using Big.Application;
+using Big.Domain;
+
+namespace Big.Tests;
+
+// S-10a (#102): the "documents received" use case. A zorgprofessional supplies the documents their
+// registration is waiting for; the handler completes the WachtOpDocumenten task via the Workflow Client
+// so the process leaves the 30-day wait and continues to beoordeling. Owner-scoped by the caller's bsn,
+// like WithdrawRegistration. (The real file upload + ZGW storage is S-10b; this is the trigger path.)
+public class ProvideDocumentsTests
+{
+    private const string Bsn = "123456782";
+
+    private static Registration Submitted(string processInstanceId = "proc-1")
+    {
+        var registration = Registration.Submit(Bsn);
+        registration.RecordProcessStarted(processInstanceId);
+        return registration;
+    }
+
+    private static ProvideDocumentsCommand Command(RegistrationId id, string bsn = Bsn) => new(id, bsn);
+
+    [Fact]
+    public async Task Providing_documents_completes_the_document_wait()
+    {
+        var store = new FakeRegistrationStore();
+        var registration = Submitted("proc-42");
+        store.Seed(registration);
+        var workflow = new FakeWorkflowClient();
+        var handler = new ProvideDocuments(store, workflow);
+
+        var outcome = await handler.HandleAsync(Command(registration.Id));
+
+        Assert.Equal(ProvideDocumentsOutcome.Accepted, outcome);
+        Assert.Equal("proc-42", workflow.CompletedDocumentWaitFor);
+    }
+
+    [Fact]
+    public async Task A_different_bsn_cannot_provide_documents()
+    {
+        // Owner-scoping: only the registration's own bsn may supply its documents. Another bsn is told
+        // NotFound (existence not revealed) and the wait is not completed.
+        var store = new FakeRegistrationStore();
+        var registration = Submitted();
+        store.Seed(registration);
+        var workflow = new FakeWorkflowClient();
+        var handler = new ProvideDocuments(store, workflow);
+
+        var outcome = await handler.HandleAsync(Command(registration.Id, bsn: "999999990"));
+
+        Assert.Equal(ProvideDocumentsOutcome.NotFound, outcome);
+        Assert.Null(workflow.CompletedDocumentWaitFor);
+    }
+
+    [Fact]
+    public async Task Providing_for_an_unknown_registration_is_not_found()
+    {
+        var store = new FakeRegistrationStore();
+        var handler = new ProvideDocuments(store, new FakeWorkflowClient());
+
+        Assert.Equal(ProvideDocumentsOutcome.NotFound, await handler.HandleAsync(Command(RegistrationId.New())));
+    }
+
+    [Fact]
+    public async Task Providing_before_a_process_started_is_accepted_without_calling_the_workflow()
+    {
+        // No process yet → no wait task to complete; the request still stands (best-effort, mirroring
+        // WithdrawRegistration) and the Workflow Client is not called.
+        var store = new FakeRegistrationStore();
+        var registration = Registration.Submit(Bsn); // no RecordProcessStarted
+        store.Seed(registration);
+        var workflow = new FakeWorkflowClient();
+        var handler = new ProvideDocuments(store, workflow);
+
+        var outcome = await handler.HandleAsync(Command(registration.Id));
+
+        Assert.Equal(ProvideDocumentsOutcome.Accepted, outcome);
+        Assert.Null(workflow.CompletedDocumentWaitFor);
+    }
+
+    [Fact]
+    public async Task Rejects_a_null_command()
+        => await Assert.ThrowsAsync<ArgumentNullException>(() =>
+            new ProvideDocuments(new FakeRegistrationStore(), new FakeWorkflowClient()).HandleAsync(null!));
+}

services/domain/Big.Tests/RegistratieVerlopenProcessorTests.cs

@@ -0,0 +1,79 @@
+using Big.Application;
+using Big.Infrastructure;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging.Abstractions;
+
+namespace Big.Tests;
+
+// S-10a (#102): the document-timeout drain loop. Mirrors BeoordelingEscalatieProcessor — acquire the
+// parked RegistratieVerlopen jobs (the tokens the 30-day boundary timer on WachtOpDocumenten spawns),
+// expire each correlated registration via the ExpireRegistrationWorker, then complete the job. A job
+// whose expiry fails is logged and left un-completed for Flowable to redeliver (§8.6).
+public class RegistratieVerlopenProcessorTests
+{
+    /// <summary>A fake client scripting the jobs to acquire and recording completions.</summary>
+    private sealed class FakeVerlopenClient(params RegistratieVerlopenJob[] jobs) : IRegistratieVerlopenClient
+    {
+        public int AcquireCount { get; private set; }
+        public List<string> Completed { get; } = [];
+
+        public Task<IReadOnlyList<RegistratieVerlopenJob>> AcquireRegistratieVerlopenJobsAsync(int maxJobs, CancellationToken ct = default)
+        {
+            AcquireCount++;
+            return Task.FromResult<IReadOnlyList<RegistratieVerlopenJob>>(jobs.Take(maxJobs).ToList());
+        }
+
+        public Task CompleteRegistratieVerlopenJobAsync(string jobId, CancellationToken ct = default)
+        {
+            Completed.Add(jobId);
+            return Task.CompletedTask;
+        }
+    }
+
+    private static ExpireRegistrationWorker Worker(FakeRegistrationStore store) => new(store);
+
+    [Fact]
+    public async Task Acquires_a_job_expires_the_registration_and_completes_the_job()
+    {
+        var store = new FakeRegistrationStore();
+        var registration = Domain.Registration.Submit("123456782");
+        store.Seed(registration);
+        var client = new FakeVerlopenClient(new RegistratieVerlopenJob("job-9", registration.Id));
+
+        var acquired = await new RegistratieVerlopenProcessor(
+            client, Worker(store), NullLogger<RegistratieVerlopenProcessor>.Instance).PumpOnceAsync(5);
+
+        Assert.Equal(1, acquired);
+        Assert.Equal(Domain.RegistrationStatus.Verlopen, (await store.GetAsync(registration.Id))!.Status);
+        Assert.Equal("job-9", Assert.Single(client.Completed));
+    }
+
+    [Fact]
+    public async Task A_failing_expiry_is_left_uncompleted_for_flowable_to_redeliver()
+    {
+        // Unknown registration → the worker throws → the job is left for redelivery, error logged.
+        var store = new FakeRegistrationStore();
+        var client = new FakeVerlopenClient(new RegistratieVerlopenJob("job-9", Domain.RegistrationId.New()));
+        var logger = new CapturingLogger<RegistratieVerlopenProcessor>();
+
+        var acquired = await new RegistratieVerlopenProcessor(client, Worker(store), logger).PumpOnceAsync(5);
+
+        Assert.Equal(1, acquired);
+        Assert.Empty(client.Completed);
+        var error = Assert.Single(logger.Entries, e => e.Level == LogLevel.Error);
+        Assert.Contains("job-9", error.Message);
+    }
+
+    [Fact]
+    public async Task Does_nothing_but_poll_when_there_are_no_jobs()
+    {
+        var client = new FakeVerlopenClient();
+
+        var acquired = await new RegistratieVerlopenProcessor(
+            client, Worker(new FakeRegistrationStore()), NullLogger<RegistratieVerlopenProcessor>.Instance).PumpOnceAsync(5);
+
+        Assert.Equal(0, acquired);
+        Assert.Equal(1, client.AcquireCount);
+        Assert.Empty(client.Completed);
+    }
+}

services/domain/Big.Tests/RegistrationTests.cs

@@ -294,4 +294,63 @@ public class RegistrationTests
         Assert.Contains("only an INGEDIEND", ex.Message);
         Assert.Equal(RegistrationStatus.Afgewezen, registration.Status);
     }
+
+    [Fact]
+    public void Expiring_an_ingediend_registration_sets_it_verlopen()
+    {
+        // The 30-day document-wait timer fired before the documents arrived (S-10a): the case is
+        // cancelled and the aggregate becomes terminal VERLOPEN.
+        var registration = Registration.Submit("123456782");
+
+        registration.Expire();
+
+        Assert.Equal(RegistrationStatus.Verlopen, registration.Status);
+    }
+
+    [Fact]
+    public void Expiring_needs_no_zaak()
+    {
+        // The timer fires on a purely time-based boundary; expiry does not depend on the zaak.
+        var registration = Registration.Submit("123456782");
+
+        registration.Expire();
+
+        Assert.Equal(RegistrationStatus.Verlopen, registration.Status);
+        Assert.Null(registration.ZaakUrl);
+    }
+
+    [Fact]
+    public void Re_expiring_an_already_verlopen_registration_is_idempotent()
+    {
+        // The RegistratieVerlopen worker job may be redelivered (§8.6); re-expiring is a no-op.
+        var registration = Registration.Submit("123456782");
+        registration.Expire();
+
+        registration.Expire();
+
+        Assert.Equal(RegistrationStatus.Verlopen, registration.Status);
+    }
+
+    [Fact]
+    public void Expiring_an_approved_registration_is_rejected()
+    {
+        var registration = Registration.Submit("123456782");
+        registration.AttachZaak(new Uri("http://openzaak/zaken/api/v1/zaken/abc"));
+        registration.Approve();
+
+        var ex = Assert.Throws<InvalidOperationException>(() => registration.Expire());
+        Assert.Contains("only an INGEDIEND", ex.Message);
+        Assert.Equal(RegistrationStatus.Ingeschreven, registration.Status);
+    }
+
+    [Fact]
+    public void Expiring_a_withdrawn_registration_is_rejected()
+    {
+        var registration = Registration.Submit("123456782");
+        registration.Withdraw();
+
+        var ex = Assert.Throws<InvalidOperationException>(() => registration.Expire());
+        Assert.Contains("only an INGEDIEND", ex.Message);
+        Assert.Equal(RegistrationStatus.Ingetrokken, registration.Status);
+    }
 }