feat(domain): herregistratie reminder sweep on a Quartz cron (S-17, closes #18) (#121)

## What & why

S-17: a BIG inscription is valid for a fixed term; before it lapses the zorgprofessional must herregistreren. This adds a **daily herregistratie reminder sweep**.

- **Domain:** `Approve(ingeschrevenOp)` now stamps the inscription moment; `HerregistratieVoor` derives the deadline (inscription + 5-year validity); `HerregistratieReminderDue(asOf)` is the single rule (inside the 90-day window, inscribed, not yet reminded); `MarkHerregistratieReminderVerstuurd()` is idempotent.
- **Store:** `FindDueForHerregistratieReminderAsync(asOf)` — the sweep's candidate set, filtered on the aggregate's own rule (no duplicated policy).
- **Application:** `HerregistratieReminderSweep` — pure over the store + an injected `TimeProvider`; flags + persists each due inscription, returns the reminded ids.
- **Infra/API:** `HerregistratieReminderJob` (Quartz `IJob`) fires the sweep on a daily cron (03:00, overridable via `Quartz__Cron`) and logs the count. `GET /registrations/{id}` surfaces `herregistratieVoor` + `herregistratieReminderVerstuurd`.

**Decisions (both raised with you before coding):** use Quartz.NET as the PRD names it — a genuine cron concern, distinct from the queue-draining pumps, which stay as-is (**ADR-0022**, proposal #120); and the reminder's observable effect is a flag on the aggregate + a log line (no outbound notification infra in v1). No coupling rule (§8) is touched — Quartz is internal to the Domain Service.

Closes #18
Closes #120

## Definition of Done

- [x] Linked Gitea issue (above).
- [x] Failing test committed before the implementation (red→green per layer: domain rule, store query, sweep).
- [x] Implementation makes the test pass; refactor commit for the 90-day knob.
- [x] Conventional Commits referencing the issue (`refs #18`).
- [ ] CI green — awaiting Gitea Actions.
- [ ] `docker compose up` reaches green health checks within 3 minutes — API boots locally with Quartz initialised; verified in CI compose smoke.
- [x] Docs updated — ADR-0022, demo-script, BACKLOG.
- [x] ADR added — `docs/architecture/adr-0022-quartz-scheduler.md`.
- [x] Demo note in `docs/demo-script.md`.

## Notes for reviewers

- **Ripple:** `Approve()` gained the inscription moment, so the two approving handlers (`ApproveRegistration`, `BeoordeelRegistratie`) now take an injected `TimeProvider`; existing tests pass a fixed clock. All three `IRegistrationStore` implementers (prod, unit fake, acceptance) got the new query.
- **Calibration knobs:** validity (5y) and reminder lead time (90d) are domain constants marked with `ponytail:` comments; promotion path to beheer config (S-15) noted in the ADR.
- **Mutation:** the Quartz job shell is excluded from Stryker, mirroring the pumps; all rule/sweep/query logic is covered.
- Local: 152 domain unit tests green; API boots with the Quartz scheduler and `/health` green.

Reviewed-on: #121

services/domain/Big.Tests/ApproveRegistrationTests.cs

@@ -19,7 +19,7 @@ public class ApproveRegistrationTests
         var acl = new FakeAclClient();
         var registration = WithZaak();
         store.Seed(registration);
-        var handler = new ApproveRegistration(store, acl);
+        var handler = new ApproveRegistration(store, acl, TimeProvider.System);
 
         await handler.HandleAsync(new ApproveRegistrationCommand(registration.Id));
 
@@ -36,7 +36,7 @@ public class ApproveRegistrationTests
     {
         var store = new FakeRegistrationStore();
         var acl = new FakeAclClient();
-        var handler = new ApproveRegistration(store, acl);
+        var handler = new ApproveRegistration(store, acl, TimeProvider.System);
 
         await Assert.ThrowsAsync<ArgumentNullException>(() => handler.HandleAsync(null!));
         Assert.Equal(0, acl.ApproveCallCount);
@@ -47,7 +47,7 @@ public class ApproveRegistrationTests
     {
         var store = new FakeRegistrationStore();
         var acl = new FakeAclClient();
-        var handler = new ApproveRegistration(store, acl);
+        var handler = new ApproveRegistration(store, acl, TimeProvider.System);
 
         var ex = await Assert.ThrowsAsync<InvalidOperationException>(
             () => handler.HandleAsync(new ApproveRegistrationCommand(RegistrationId.New())));
@@ -62,7 +62,7 @@ public class ApproveRegistrationTests
         var acl = new FakeAclClient();
         var registration = Registration.Submit("123456782"); // no zaak yet
         store.Seed(registration);
-        var handler = new ApproveRegistration(store, acl);
+        var handler = new ApproveRegistration(store, acl, TimeProvider.System);
 
         var ex = await Assert.ThrowsAsync<InvalidOperationException>(
             () => handler.HandleAsync(new ApproveRegistrationCommand(registration.Id)));
@@ -77,7 +77,7 @@ public class ApproveRegistrationTests
         var acl = new FakeAclClient();
         var registration = WithZaak();
         store.Seed(registration);
-        var handler = new ApproveRegistration(store, acl);
+        var handler = new ApproveRegistration(store, acl, TimeProvider.System);
 
         await handler.HandleAsync(new ApproveRegistrationCommand(registration.Id));
         await handler.HandleAsync(new ApproveRegistrationCommand(registration.Id));

services/domain/Big.Tests/BeoordeelRegistratieTests.cs

@@ -29,7 +29,7 @@ public class BeoordeelRegistratieTests
         var registration = WithZaak();
         store.Seed(registration);
         var tasks = TaskFor(registration);
-        var handler = new BeoordeelRegistratie(store, acl, tasks);
+        var handler = new BeoordeelRegistratie(store, acl, tasks, TimeProvider.System);
 
         await handler.HandleAsync(new BeoordeelRegistratieCommand(registration.Id, BeoordelingsBesluit.Goedkeuren));
 
@@ -50,7 +50,7 @@ public class BeoordeelRegistratieTests
         var registration = WithZaak();
         store.Seed(registration);
         var tasks = TaskFor(registration);
-        var handler = new BeoordeelRegistratie(store, acl, tasks);
+        var handler = new BeoordeelRegistratie(store, acl, tasks, TimeProvider.System);
 
         await handler.HandleAsync(new BeoordeelRegistratieCommand(registration.Id, BeoordelingsBesluit.Afwijzen));
 
@@ -69,7 +69,7 @@ public class BeoordeelRegistratieTests
         var registration = WithZaak();
         registration.TakeIntoBehandeling();
         store.Seed(registration);
-        var handler = new BeoordeelRegistratie(store, acl, TaskFor(registration));
+        var handler = new BeoordeelRegistratie(store, acl, TaskFor(registration), TimeProvider.System);
 
         await handler.HandleAsync(new BeoordeelRegistratieCommand(registration.Id, BeoordelingsBesluit.Goedkeuren));
 
@@ -81,7 +81,7 @@ public class BeoordeelRegistratieTests
     {
         var store = new FakeRegistrationStore();
         var acl = new FakeAclClient();
-        var handler = new BeoordeelRegistratie(store, acl, new FakeUserTaskClient([]));
+        var handler = new BeoordeelRegistratie(store, acl, new FakeUserTaskClient([]), TimeProvider.System);
 
         await Assert.ThrowsAsync<ArgumentNullException>(() => handler.HandleAsync(null!));
         Assert.Equal(0, acl.ApproveCallCount);
@@ -93,7 +93,7 @@ public class BeoordeelRegistratieTests
     {
         var store = new FakeRegistrationStore();
         var acl = new FakeAclClient();
-        var handler = new BeoordeelRegistratie(store, acl, new FakeUserTaskClient([]));
+        var handler = new BeoordeelRegistratie(store, acl, new FakeUserTaskClient([]), TimeProvider.System);
 
         var ex = await Assert.ThrowsAsync<InvalidOperationException>(() =>
             handler.HandleAsync(new BeoordeelRegistratieCommand(RegistrationId.New(), BeoordelingsBesluit.Goedkeuren)));
@@ -108,7 +108,7 @@ public class BeoordeelRegistratieTests
         var acl = new FakeAclClient();
         var registration = Registration.Submit("123456782"); // no zaak yet
         store.Seed(registration);
-        var handler = new BeoordeelRegistratie(store, acl, TaskFor(registration));
+        var handler = new BeoordeelRegistratie(store, acl, TaskFor(registration), TimeProvider.System);
 
         var ex = await Assert.ThrowsAsync<InvalidOperationException>(() =>
             handler.HandleAsync(new BeoordeelRegistratieCommand(registration.Id, BeoordelingsBesluit.Goedkeuren)));
@@ -123,7 +123,7 @@ public class BeoordeelRegistratieTests
         var acl = new FakeAclClient();
         var registration = WithZaak();
         store.Seed(registration);
-        var handler = new BeoordeelRegistratie(store, acl, TaskFor(registration));
+        var handler = new BeoordeelRegistratie(store, acl, TaskFor(registration), TimeProvider.System);
 
         await handler.HandleAsync(new BeoordeelRegistratieCommand(registration.Id, BeoordelingsBesluit.Goedkeuren));
         await handler.HandleAsync(new BeoordeelRegistratieCommand(registration.Id, BeoordelingsBesluit.Goedkeuren));
@@ -139,7 +139,7 @@ public class BeoordeelRegistratieTests
         var acl = new FakeAclClient();
         var registration = WithZaak();
         store.Seed(registration);
-        var handler = new BeoordeelRegistratie(store, acl, TaskFor(registration));
+        var handler = new BeoordeelRegistratie(store, acl, TaskFor(registration), TimeProvider.System);
 
         await handler.HandleAsync(new BeoordeelRegistratieCommand(registration.Id, BeoordelingsBesluit.Afwijzen));
         await handler.HandleAsync(new BeoordeelRegistratieCommand(registration.Id, BeoordelingsBesluit.Afwijzen));
@@ -158,7 +158,7 @@ public class BeoordeelRegistratieTests
         var registration = WithZaak();
         store.Seed(registration);
         var tasks = new FakeUserTaskClient([]); // no open task for this registration
-        var handler = new BeoordeelRegistratie(store, acl, tasks);
+        var handler = new BeoordeelRegistratie(store, acl, tasks, TimeProvider.System);
 
         await handler.HandleAsync(new BeoordeelRegistratieCommand(registration.Id, BeoordelingsBesluit.Goedkeuren));
 

services/domain/Big.Tests/Fakes.cs

@@ -26,6 +26,11 @@ internal sealed class FakeRegistrationStore : IRegistrationStore
         => Task.FromResult(_byId.Values.FirstOrDefault(r =>
             r.Bsn == bsn && r.Status is RegistrationStatus.Ingediend or RegistrationStatus.InBehandeling));
 
+    public Task<IReadOnlyList<Registration>> FindDueForHerregistratieReminderAsync(
+        DateTimeOffset asOf, CancellationToken ct = default)
+        => Task.FromResult<IReadOnlyList<Registration>>(
+            _byId.Values.Where(r => r.HerregistratieReminderDue(asOf)).ToList());
+
     public void Seed(Registration registration) => _byId[registration.Id] = registration;
 }
 
@@ -85,6 +90,13 @@ internal sealed class FakeUserTaskClient(IReadOnlyList<BeoordelingTask> open) :
     }
 }
 
+/// <summary>A <see cref="TimeProvider"/> pinned to a fixed instant, so time-based use cases (the
+/// herregistratie sweep, S-17) are deterministic without the TimeProvider.Testing package.</summary>
+internal sealed class FixedClock(DateTimeOffset now) : TimeProvider
+{
+    public override DateTimeOffset GetUtcNow() => now;
+}
+
 /// <summary>A fake ACL client that records the bsn it was asked to open a zaak for and returns a
 /// fixed zaak URL.</summary>
 internal sealed class FakeAclClient(Uri? zaakUrl = null) : IAclClient

services/domain/Big.Tests/HerregistratieReminderSweepTests.cs

@@ -0,0 +1,67 @@
+using Big.Application;
+using Big.Domain;
+
+namespace Big.Tests;
+
+// S-17 (#18): the sweep behind the Quartz job. It reminds every inscription whose herregistratie
+// reminder is due, marks each so a re-fire is a no-op (§8.6), and returns the reminded ids. Pure over
+// the store + an injected clock — no Quartz here.
+public class HerregistratieReminderSweepTests
+{
+    private static readonly DateTimeOffset Now = new(2026, 7, 23, 0, 0, 0, TimeSpan.Zero);
+
+    private static Registration Inscribed(string bsn, DateTimeOffset ingeschrevenOp)
+    {
+        var registration = Registration.Submit(bsn);
+        registration.AttachZaak(FakeAclClient.DefaultZaakUrl);
+        registration.Approve(ingeschrevenOp);
+        return registration;
+    }
+
+    // Inscribed exactly (geldigheid - herinneringstermijn) before Now: the reminder window is open.
+    private static Registration Due(string bsn)
+        => Inscribed(bsn, Now - Registration.HerregistratieGeldigheid + Registration.Herinneringstermijn);
+
+    [Fact]
+    public async Task Reminds_and_persists_every_due_inscription_and_returns_their_ids()
+    {
+        var store = new FakeRegistrationStore();
+        var a = Due("123456782");
+        var b = Due("111111110");
+        var freshlyInscribed = Inscribed("222222222", Now); // not yet in the window
+        store.Seed(a);
+        store.Seed(b);
+        store.Seed(freshlyInscribed);
+
+        var reminded = await new HerregistratieReminderSweep(store, new FixedClock(Now)).SweepAsync();
+
+        Assert.Equal(new HashSet<RegistrationId> { a.Id, b.Id }, reminded.ToHashSet());
+        Assert.True((await store.GetAsync(a.Id))!.HerregistratieReminderVerstuurd);
+        Assert.True((await store.GetAsync(b.Id))!.HerregistratieReminderVerstuurd);
+        Assert.False((await store.GetAsync(freshlyInscribed.Id))!.HerregistratieReminderVerstuurd);
+        Assert.Equal(2, store.SaveCount);
+    }
+
+    [Fact]
+    public async Task A_second_sweep_reminds_no_one_again()
+    {
+        var store = new FakeRegistrationStore();
+        store.Seed(Due("123456782"));
+        var sweep = new HerregistratieReminderSweep(store, new FixedClock(Now));
+
+        await sweep.SweepAsync();
+        var second = await sweep.SweepAsync();
+
+        Assert.Empty(second);
+        Assert.Equal(1, store.SaveCount); // only the first sweep persisted anything
+    }
+
+    [Fact]
+    public async Task Reminds_no_one_when_nothing_is_due()
+    {
+        var store = new FakeRegistrationStore();
+        store.Seed(Inscribed("123456782", Now)); // freshly inscribed — deadline is 5 years off
+
+        Assert.Empty(await new HerregistratieReminderSweep(store, new FixedClock(Now)).SweepAsync());
+    }
+}

services/domain/Big.Tests/InMemoryRegistrationStoreTests.cs

@@ -79,7 +79,7 @@ public class InMemoryRegistrationStoreTests
         switch (transition)
         {
             case nameof(Registration.Withdraw): registration.Withdraw(); break;
-            case nameof(Registration.Approve): registration.Approve(); break;
+            case nameof(Registration.Approve): registration.Approve(DateTimeOffset.UtcNow); break;
             case nameof(Registration.Reject): registration.Reject(); break;
             case nameof(Registration.Expire): registration.Expire(); break;
         }
@@ -96,4 +96,27 @@ public class InMemoryRegistrationStoreTests
 
         Assert.Null(await store.FindOpenByBsnAsync("123456782"));
     }
+
+    [Fact]
+    public async Task Finds_only_the_inscriptions_due_for_a_herregistratie_reminder()
+    {
+        var now = new DateTimeOffset(2026, 7, 23, 0, 0, 0, TimeSpan.Zero);
+        var store = new InMemoryRegistrationStore();
+
+        var due = Registration.Submit("123456782");
+        due.AttachZaak(new Uri("http://openzaak/zaken/api/v1/zaken/abc"));
+        due.Approve(now - Registration.HerregistratieGeldigheid + Registration.Herinneringstermijn);
+        await store.SaveAsync(due);
+
+        var freshlyInscribed = Registration.Submit("111111110");
+        freshlyInscribed.AttachZaak(new Uri("http://openzaak/zaken/api/v1/zaken/def"));
+        freshlyInscribed.Approve(now);
+        await store.SaveAsync(freshlyInscribed);
+
+        await store.SaveAsync(Registration.Submit("222222222")); // still INGEDIEND — never inscribed
+
+        var result = await store.FindDueForHerregistratieReminderAsync(now);
+
+        Assert.Equal([due.Id], result.Select(r => r.Id).ToArray());
+    }
 }

services/domain/Big.Tests/RegistrationHerregistratieTests.cs

@@ -0,0 +1,90 @@
+using Big.Domain;
+
+namespace Big.Tests;
+
+// S-17 (#18): a BIG inscription is valid for a fixed term; before it lapses the zorgprofessional must
+// herregistreren. The aggregate records when it was inscribed, derives the herregistratie deadline, and
+// answers whether a reminder is due as of a given moment — the single rule the Quartz sweep and the
+// store query both build on. All arithmetic is against an explicit "now" so it is wall-clock-free.
+public class RegistrationHerregistratieTests
+{
+    private static readonly DateTimeOffset Now = new(2026, 7, 23, 0, 0, 0, TimeSpan.Zero);
+
+    // The moment the reminder window opens: inscribed exactly (geldigheid - herinneringstermijn) ago.
+    private static DateTimeOffset InscribedSoDueAt(DateTimeOffset asOf)
+        => asOf - Registration.HerregistratieGeldigheid + Registration.Herinneringstermijn;
+
+    private static Registration Inscribed(DateTimeOffset ingeschrevenOp)
+    {
+        var registration = Registration.Submit("123456782");
+        registration.AttachZaak(FakeAclClient.DefaultZaakUrl);
+        registration.Approve(ingeschrevenOp);
+        return registration;
+    }
+
+    [Fact]
+    public void Approving_records_the_inscription_moment_and_the_herregistratie_deadline()
+    {
+        var registration = Inscribed(Now);
+
+        Assert.Equal(Now, registration.IngeschrevenOp);
+        Assert.Equal(Now + Registration.HerregistratieGeldigheid, registration.HerregistratieVoor);
+    }
+
+    [Fact]
+    public void A_reminder_is_due_the_moment_the_window_before_the_deadline_opens()
+    {
+        var registration = Inscribed(InscribedSoDueAt(Now));
+
+        Assert.True(registration.HerregistratieReminderDue(Now));
+    }
+
+    [Fact]
+    public void A_reminder_is_not_yet_due_one_day_before_the_window_opens()
+    {
+        var registration = Inscribed(InscribedSoDueAt(Now) + TimeSpan.FromDays(1));
+
+        Assert.False(registration.HerregistratieReminderDue(Now));
+    }
+
+    [Fact]
+    public void A_registration_that_is_not_ingeschreven_is_never_due_and_has_no_deadline()
+    {
+        var registration = Registration.Submit("123456782"); // INGEDIEND, never inscribed
+
+        Assert.Null(registration.IngeschrevenOp);
+        Assert.Null(registration.HerregistratieVoor);
+        Assert.False(registration.HerregistratieReminderDue(Now));
+    }
+
+    [Fact]
+    public void A_reminded_registration_is_no_longer_due()
+    {
+        var registration = Inscribed(InscribedSoDueAt(Now));
+
+        registration.MarkHerregistratieReminderVerstuurd();
+
+        Assert.True(registration.HerregistratieReminderVerstuurd);
+        Assert.False(registration.HerregistratieReminderDue(Now));
+    }
+
+    [Fact]
+    public void Marking_the_reminder_sent_twice_is_idempotent()
+    {
+        var registration = Inscribed(InscribedSoDueAt(Now));
+
+        registration.MarkHerregistratieReminderVerstuurd();
+        registration.MarkHerregistratieReminderVerstuurd();
+
+        Assert.True(registration.HerregistratieReminderVerstuurd);
+    }
+
+    [Fact]
+    public void Marking_a_reminder_on_a_registration_that_is_not_ingeschreven_is_rejected()
+    {
+        var registration = Registration.Submit("123456782");
+
+        var ex = Assert.Throws<InvalidOperationException>(() => registration.MarkHerregistratieReminderVerstuurd());
+        Assert.Contains("INGESCHREVEN", ex.Message);
+    }
+}

services/domain/Big.Tests/RegistrationTests.cs

@@ -4,6 +4,9 @@ namespace Big.Tests;
 
 public class RegistrationTests
 {
+    // A fixed inscription moment for the approval tests; its exact value is irrelevant to them.
+    private static readonly DateTimeOffset Ingeschreven = new(2026, 1, 1, 0, 0, 0, TimeSpan.Zero);
+
     [Fact]
     public void Submitting_a_registration_starts_in_ingediend()
     {
@@ -103,7 +106,7 @@ public class RegistrationTests
         var registration = Registration.Submit("123456782");
         registration.AttachZaak(new Uri("http://openzaak/zaken/api/v1/zaken/abc"));
 
-        registration.Approve();
+        registration.Approve(Ingeschreven);
 
         Assert.Equal(RegistrationStatus.Ingeschreven, registration.Status);
     }
@@ -113,7 +116,7 @@ public class RegistrationTests
     {
         var registration = Registration.Submit("123456782");
 
-        var ex = Assert.Throws<InvalidOperationException>(() => registration.Approve());
+        var ex = Assert.Throws<InvalidOperationException>(() => registration.Approve(Ingeschreven));
 
         Assert.Contains("no zaak", ex.Message, StringComparison.OrdinalIgnoreCase);
         Assert.Equal(RegistrationStatus.Ingediend, registration.Status);
@@ -124,9 +127,9 @@ public class RegistrationTests
     {
         var registration = Registration.Submit("123456782");
         registration.AttachZaak(new Uri("http://openzaak/zaken/api/v1/zaken/abc"));
-        registration.Approve();
+        registration.Approve(Ingeschreven);
 
-        var ex = Assert.Throws<InvalidOperationException>(() => registration.Approve());
+        var ex = Assert.Throws<InvalidOperationException>(() => registration.Approve(Ingeschreven));
         Assert.Contains("only an INGEDIEND", ex.Message);
         Assert.Equal(RegistrationStatus.Ingeschreven, registration.Status);
     }
@@ -157,7 +160,7 @@ public class RegistrationTests
     {
         var registration = Registration.Submit("123456782");
         registration.AttachZaak(new Uri("http://openzaak/zaken/api/v1/zaken/abc"));
-        registration.Approve();
+        registration.Approve(Ingeschreven);
 
         var ex = Assert.Throws<InvalidOperationException>(() => registration.TakeIntoBehandeling());
         Assert.Contains("only an INGEDIEND", ex.Message);
@@ -171,7 +174,7 @@ public class RegistrationTests
         registration.AttachZaak(new Uri("http://openzaak/zaken/api/v1/zaken/abc"));
         registration.TakeIntoBehandeling();
 
-        registration.Approve();
+        registration.Approve(Ingeschreven);
 
         Assert.Equal(RegistrationStatus.Ingeschreven, registration.Status);
     }
@@ -218,7 +221,7 @@ public class RegistrationTests
         var approveEx = Assert.Throws<InvalidOperationException>(() =>
         {
             registration.AttachZaak(new Uri("http://openzaak/zaken/api/v1/zaken/abc"));
-            registration.Approve();
+            registration.Approve(Ingeschreven);
         });
         Assert.Contains("IN_BEHANDELING", approveEx.Message);
 
@@ -277,7 +280,7 @@ public class RegistrationTests
     {
         var registration = Registration.Submit("123456782");
         registration.AttachZaak(new Uri("http://openzaak/zaken/api/v1/zaken/abc"));
-        registration.Approve();
+        registration.Approve(Ingeschreven);
 
         var ex = Assert.Throws<InvalidOperationException>(() => registration.Withdraw());
         Assert.Contains("only an INGEDIEND", ex.Message);
@@ -336,7 +339,7 @@ public class RegistrationTests
     {
         var registration = Registration.Submit("123456782");
         registration.AttachZaak(new Uri("http://openzaak/zaken/api/v1/zaken/abc"));
-        registration.Approve();
+        registration.Approve(Ingeschreven);
 
         var ex = Assert.Throws<InvalidOperationException>(() => registration.Expire());
         Assert.Contains("only an INGEDIEND", ex.Message);