fix(ci): pin upload-artifact to @v3 — @v4 refuses to run on Gitea (refs #47 )

The artifact step failed the mutation job: upload-artifact@v4 bundles @actions/artifact v2, which hard-aborts on any non-github.com server ("not supported on GHES"), even though Gitea 1.25 stores artifacts fine. @v3 uses the older protocol Gitea speaks and has no GHES guard — a drop-in swap (same inputs). Document it as gotcha §4 and correct the CI runbook note. Refs #47. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ci(acl): publish the Stryker HTML report as a CI artifact (refs #47 )
2026-06-25 15:28:07 +02:00 · 2026-06-25 15:21:26 +02:00 · 2026-06-25 14:59:41 +02:00 · 2026-06-25 14:58:22 +02:00 · 2026-06-25 14:58:00 +02:00 · 2026-06-25 14:57:51 +02:00
33 changed files with 1286 additions and 719 deletions
@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "dotnet-stryker": {
+      "version": "4.15.0",
+      "commands": [
+        "dotnet-stryker"
+      ],
+      "rollForward": false
+    }
+  }
+}
@@ -17,7 +17,7 @@ permissions:

 jobs:
  lint:
-    runs-on: respellion-linux
+    runs-on: ubuntu-latest
    steps:
      - uses: https://github.com/actions/checkout@v4
      - uses: https://github.com/actions/setup-dotnet@v4
@@ -26,7 +26,7 @@ jobs:
      - run: make lint

  build:
-    runs-on: respellion-linux
+    runs-on: ubuntu-latest
    steps:
      - uses: https://github.com/actions/checkout@v4
      - uses: https://github.com/actions/setup-dotnet@v4
@@ -35,7 +35,7 @@ jobs:
      - run: make build

  unit:
-    runs-on: respellion-linux
+    runs-on: ubuntu-latest
    steps:
      - uses: https://github.com/actions/checkout@v4
      - uses: https://github.com/actions/setup-dotnet@v4
@@ -43,8 +43,34 @@ jobs:
          dotnet-version: '10.0.x'
      - run: make unit

+  mutation:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: https://github.com/actions/checkout@v4
+      - uses: https://github.com/actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
+      - run: make mutation
+      # Publish the Stryker HTML report. `if: always()` uploads it even when the
+      # ratchet fails — that is exactly when you want to inspect the survivors.
+      # Glob handles Stryker's non-deterministic StrykerOutput/<timestamp>/ dir.
+      # Pinned to @v3 deliberately: @v4 refuses to run on Gitea (GHES guard) —
+      # see docs/runbooks/gitea-actions-gotchas.md §4.
+      - uses: https://github.com/actions/upload-artifact@v3
+        if: always()
+        with:
+          name: acl-mutation-report
+          path: services/acl/StrykerOutput/**/reports/mutation-report.html
+          if-no-files-found: warn
+
  compose-smoke:
-    runs-on: respellion-linux
+    runs-on: ubuntu-latest
    steps:
      - uses: https://github.com/actions/checkout@v4
      - run: make smoke
+      - name: dump container logs on failure
+        if: failure()
+        run: docker compose -f infra/docker-compose.yml logs --no-color --tail=80 oz-init openzaak nrc-init nrc-web flowable-init keycloak acl bff 2>&1 || true
+      - name: tear down on failure
+        if: failure()
+        run: docker compose -f infra/docker-compose.yml down --volumes 2>&1 || true
@@ -15,6 +15,9 @@ coverage*.json
 coverage*.xml
 *.coverage

+# Stryker.NET mutation-testing reports (regenerated by `make mutation`)
+StrykerOutput/
+
 # Rider / VS / VS Code
 .idea/
 .vs/
@@ -7,7 +7,22 @@

 SLN        := register-referentie.slnx
 COMPOSE    := infra/docker-compose.yml
-HEALTH_URL := http://localhost:8080/health
+# Long-running services with a healthcheck — the smoke polls these for readiness
+# (infra/wait-healthy.sh). One-shot init jobs (oz-init, nrc-init, flowable-init)
+# are not polled; they only need to have run. See docs/runbooks/gitea-actions-gotchas.md.
+WAIT_SVCS  := openzaak nrc-web acl bff
+# Config files (OpenZaak data.yaml, Keycloak realms, Flowable BPMN) are streamed
+# into external named volumes via `docker cp` (infra/seed-config.sh) instead of
+# bind-mounted, because bind mounts don't reach sibling containers on the
+# containerized CI runner. SEED populates them; run it before every `up`. The
+# volumes are `external`, so compose won't remove them — CFG_VOLS lists them for
+# explicit teardown. See docs/runbooks/gitea-actions-gotchas.md.
+SEED       := bash infra/seed-config.sh
+CFG_VOLS   := rr-oz-config rr-kc-realms rr-fl-bpmn
+# Local-only stack: same services but config is bind-mounted (no seed step), so a
+# plain `docker compose -f infra/docker-compose.local.yml up` works on any local
+# engine. This is the no-make / Windows-friendly path. See that file's header.
+LOCAL_COMPOSE := infra/docker-compose.local.yml
 OZ_COMPOSE  := infra/openzaak/docker-compose.yml
 OZ_BASE     := http://localhost:8000
 NRC_COMPOSE := infra/opennotificaties/docker-compose.yml
@@ -28,10 +43,10 @@ export DOCKER_HOST := unix://$(PODMAN_SOCK)
 endif
 endif

-.PHONY: ci lint build unit smoke down changelog openzaak-up openzaak-smoke openzaak-seed openzaak-down stack-up stack-smoke stack-down keycloak-up keycloak-smoke keycloak-down flowable-up flowable-smoke flowable-down help
+.PHONY: ci lint build unit mutation smoke up down local local-down changelog openzaak-up openzaak-smoke openzaak-seed openzaak-down stack-up stack-smoke stack-down keycloak-up keycloak-smoke keycloak-down flowable-up flowable-smoke flowable-down help

-## ci: run the full pipeline — lint, build, unit, smoke (mirrors Gitea Actions)
-ci: lint build unit smoke
+## ci: run the full pipeline — lint, build, unit, mutation, smoke (mirrors Gitea Actions)
+ci: lint build unit mutation smoke

 ## lint: verify formatting (no changes)
 lint:
@@ -45,14 +60,47 @@ build:
 unit:
 	dotnet test $(SLN) -c Release

-## smoke: compose up (wait for healthy), curl /health, then tear down
-smoke:
-	docker compose -f $(COMPOSE) up -d --build --wait
-	bash -c 'curl -fsS $(HEALTH_URL); rc=$$?; docker compose -f $(COMPOSE) down --volumes; exit $$rc'
+## mutation: run the Stryker.NET ratchet on the ACL (fails below the recorded baseline)
+# Stryker is pinned as a local dotnet tool (.config/dotnet-tools.json); `tool restore`
+# makes `make mutation` work from a fresh clone. Config + break threshold (the ratchet,
+# CLAUDE.md §5) live in services/acl/stryker-config.json. The ACL is the first service
+# with branching logic, so it sets the repo-wide baseline; later slices ratchet it up.
+mutation:
+	dotnet tool restore
+	cd services/acl && dotnet stryker

-## down: stop and remove the local stack
+## smoke: seed config, bring the whole stack up, wait for health-checked services, tear down
+# SEED populates the external config volumes first (upstream images used verbatim;
+# only our acl/bff are built). `up -d --build` starts EVERYTHING. Readiness is
+# checked by infra/wait-healthy.sh polling the durable, health-checked services
+# ($(WAIT_SVCS)) via `docker inspect` — portable across docker compose and
+# podman-compose, and needing no `--wait` flag or host port access. The one-shots
+# (oz-init, flowable-init) aren't polled; they just need to have run.
+smoke:
+	$(SEED) oz kc fl
+	docker compose -f $(COMPOSE) up -d --build
+	bash -c 'WAIT_TIMEOUT=420 bash infra/wait-healthy.sh $(WAIT_SVCS); rc=$$?; docker compose -f $(COMPOSE) down --volumes; docker volume rm -f $(CFG_VOLS) >/dev/null 2>&1; exit $$rc'
+
+## up: seed config volumes and start the full stack (use instead of bare
+## `docker compose up`, which can't self-seed the external config volumes)
+up:
+	$(SEED) oz kc fl
+	docker compose -f $(COMPOSE) up -d --build
+
+## down: stop and remove the local stack (incl. the external config volumes)
 down:
 	docker compose -f $(COMPOSE) down --volumes
+	-docker volume rm -f $(CFG_VOLS)
+
+## local: bring up the bind-mount stack (no seed step) and wait for health
+## (Windows / no-make users: run `docker compose -f infra/docker-compose.local.yml up -d --build` directly)
+local:
+	docker compose -f $(LOCAL_COMPOSE) up -d --build
+	WAIT_TIMEOUT=420 bash infra/wait-healthy.sh $(WAIT_SVCS)
+
+## local-down: stop and remove the bind-mount stack
+local-down:
+	docker compose -f $(LOCAL_COMPOSE) down --volumes

 ## changelog: regenerate CHANGELOG.md from Conventional Commits (git-cliff)
 changelog:
@@ -60,11 +108,11 @@ changelog:

 ## openzaak-up: start the OpenZaak stack (migrations run on first start)
 openzaak-up:
+	$(SEED) oz
 	docker compose -f $(OZ_COMPOSE) up -d

 ## openzaak-smoke: start OpenZaak, then assert it is up with auth enforced
-openzaak-smoke:
-	docker compose -f $(OZ_COMPOSE) up -d
+openzaak-smoke: openzaak-up
 	@bash -c 'set -e; \
 	  echo "waiting for OpenZaak to respond..."; \
 	  for i in $$(seq 1 60); do \
@@ -88,9 +136,11 @@ openzaak-seed: openzaak-up
 ## openzaak-down: stop and remove the OpenZaak stack (wipes data)
 openzaak-down:
 	docker compose -f $(OZ_COMPOSE) down --volumes
+	-docker volume rm -f rr-oz-config

 ## stack-up: start OpenZaak + Open Notificaties together (shared network)
 stack-up:
+	$(SEED) oz
 	docker compose $(STACK_FILES) up -d

 ## stack-smoke: start both, assert OpenZaak (403/302/200) and NRC (302) are reachable
@@ -110,9 +160,11 @@ stack-smoke: stack-up
 ## stack-down: stop and remove both stacks (wipes data)
 stack-down:
 	docker compose $(STACK_FILES) down --volumes
+	-docker volume rm -f rr-oz-config

 ## keycloak-up: start Keycloak with the four imported realms
 keycloak-up:
+	$(SEED) kc
 	docker compose -f $(KC_COMPOSE) up -d

 ## keycloak-smoke: start Keycloak, then verify each realm logs in + returns its claim
@@ -125,9 +177,11 @@ keycloak-smoke: keycloak-up
 ## keycloak-down: stop and remove Keycloak
 keycloak-down:
 	docker compose -f $(KC_COMPOSE) down --volumes
+	-docker volume rm -f rr-kc-realms

 ## flowable-up: start Flowable (deploys registratie.bpmn on boot)
 flowable-up:
+	$(SEED) fl
 	docker compose -f $(FL_COMPOSE) up -d

 ## flowable-smoke: start Flowable, then verify a started instance waits on the external task
@@ -140,6 +194,7 @@ flowable-smoke: flowable-up
 ## flowable-down: stop and remove Flowable
 flowable-down:
 	docker compose -f $(FL_COMPOSE) down --volumes
+	-docker volume rm -f rr-fl-bpmn

 ## help: list available targets
 help:
@@ -0,0 +1,68 @@
+# ADR-0005: Stryker.NET for mutation testing, baseline on the ACL
+
+- **Status:** Accepted
+- **Date:** 2026-06-25
+- **Deciders:** Respellion engineering
+- **Relates to:** S-04b (#47); proposed in #51; supports CLAUDE.md §5 (mutation ratchet) and §3 (Definition of Done)
+
+## Context
+
+CLAUDE.md §5 mandates Stryker on every PR with a **ratchet**: CI fails on a regression
+below the established baseline, and the baseline only ever moves up. §3 lists "mutation
+(ratchet)" as a Definition-of-Done gate for **every** slice. Yet no baseline existed — so,
+strictly, no slice could satisfy that gate. S-04b establishes it.
+
+The ACL is the natural place to set the first baseline: it is the first service with real
+branching logic — `OpenZaakGateway` (HTTP contract, geo CRS headers, error handling),
+`ZgwToken` (HS256 JWT minting), and the `AclService` default-fill mapping. We need a tool
+that:
+
+- mutates C# and runs the existing xUnit suite per mutant,
+- is reproducible (same version locally and in CI, no global install),
+- understands this repo's `.slnx` solution format (used repo-wide),
+- emits a break threshold CI can gate on.
+
+## Decision
+
+**Use [Stryker.NET](https://stryker-mutator.io/docs/stryker-net/) (`dotnet-stryker`),
+pinned as a local dotnet tool**, configured in solution mode against `Acl.slnx`.
+
+- Pinned in `.config/dotnet-tools.json` (v4.15.0); `dotnet tool restore` makes
+  `make mutation` reproducible from a fresh clone, locally and in CI — no global install.
+- **Solution mode** (`stryker-config.json` → `solution: Acl.slnx`) mutates the two projects
+  under test (`Acl.Application`, `Acl.Infrastructure`); `Acl.Api` is untested and skipped.
+  Stryker 4.15 reads `.slnx` directly, so no throwaway `.sln` shim is needed.
+- A `mutation` make target runs it; it is wired into `make ci` and a parallel Gitea Actions
+  `mutation` job, keeping `make ci` an exact mirror of the pipeline.
+
+**Baseline:** writing S-04b's tests surfaced that the ACL suite was thin — the initial
+score was **35%** (survivors: unasserted CRS headers, null guards, error paths, and JWT
+claims). Those tests were strengthened (killing the mutants honestly rather than lowering
+the bar), raising the score to **95%**. The enforced `break` threshold is set to **90%** —
+one-mutant headroom over the ~20-mutant surface, since a single mutant is ≈5%.
+
+## Consequences
+
+- **Positive:** test *strength* is gated, not just coverage; the ratchet protects the ACL's
+  ZGW contract logic; the baseline is repo-wide and ratchets upward per §5.
+- **Cost:** a new dependency (`dotnet-stryker`) and a slower CI job than unit tests (~25 s on
+  the small ACL). Pinned + tool-restored, so reproducible.
+- **One accepted survivor:** a mutation of the empty-response *exception message string*.
+  Asserting exception message text is brittle and the behaviour (type + control flow) is
+  unchanged — treated as an equivalent mutant, not a test gap.
+- **Commitment:** later slices ratchet the threshold up deliberately, never down (§5). New
+  services add their own mutation run as they gain branching logic (BFF, Domain, …).
+- **Replaceable by:** no realistic .NET alternative — Stryker.NET is the tool §5 already
+  names; the fallback is no mutation testing, which §5 forbids.
+
+## Alternatives considered
+
+- **Global `dotnet tool install -g`** — rejected: not reproducible/pinned per clone; the
+  local manifest gives every checkout and the CI runner the same version.
+- **Mutate the whole `register-referentie.slnx`** — rejected for this slice: scopes the
+  baseline to services with no logic yet (BFF skeleton), diluting the signal. Each service
+  opts in as it gains logic.
+- **Application-only scope** — rejected: would leave `Acl.Infrastructure`'s HTTP/JWT logic —
+  the riskiest code — unguarded by the ratchet.
+- **Coverage gate instead of mutation** — rejected: line coverage does not measure whether
+  tests would *catch* a regression; that is the whole point of §5.
@@ -1,46 +0,0 @@
-# FDS-architectuur — Open Register
-
-Deze map bevat de architectuurbesluiten en de engineer-documentatie voor de FDS-kant van deze
-referentie-applicatie: deelnemen aan het Federatief Datastelsel als **afnemer**.
-
-De strategische inzet, de slices en de portfoliostatus staan in het Innovation Lab-repo,
-`Respellion/innovation-lab`, onder `projects/open-register-fd/`. Daar staan ook de
-architectuurblauwdruk, de FDS gap-analyse en de privacy-views.
-
-## Documenten
-
-| Document | Waarvoor |
-|---|---|
-| [`c4-component-view.md`](c4-component-view.md) | Componentview op niveau 3: ports en adapters, en welke views nog waarde toevoegen |
-| [`slice-1-proposal.md`](slice-1-proposal.md) | Het bouwbare eerste increment; plak dit in een `poc-voorstel`-issue |
-| `adr/` | De geaccepteerde architectuurbesluiten, ADR-0001 tot en met ADR-0006. Zie de tabel hieronder. |
-
-## Architecture Decision Records
-
-Een ADR legt een besluit vast dat **vaststaat**, met de context en de gevolgen, zodat het niet stil
-opnieuw wordt uitgevochten. Statuswaarden: `proposed` → `accepted` → (`vervangen door ADR-NNNN` |
-`deprecated`).
-
-Een geaccepteerde ADR wijzigen betekent een nieuwe ADR schrijven die de oude vervangt. Wij
-herschrijven de historie nooit.
-
-ADRs liggen naast governance. Acceptatie volgt de asynchrone bezwaarronde uit
-`Respellion/innovation-lab`, `operating-model/operating-model.md`, sectie *Besluitvorming*.
-
-| ADR | Besluit | Status |
-|---|---|---|
-| [0001](adr/0001-acl-at-every-register-boundary.md) | Anti-Corruption Layer op elke registergrens | accepted |
-| [0002](adr/0002-fsc-for-connectivity.md) | FSC voor connectiviteit tussen organisaties, geen ruwe REST | accepted |
-| [0003](adr/0003-pbac-via-opa.md) | Policy-based access control via OPA, FTV-klaar | accepted |
-| [0004](adr/0004-bounded-cache.md) | Begrensde cache; registers blijven systeem van registratie | accepted |
-| [0005](adr/0005-ldv-verwerkingenlog.md) | Verwerkingenlog via event-emissie, in lijn met LDV | accepted |
-| [0006](adr/0006-module-boundary-and-reuse.md) | Modulegrens en hergebruikstrategie: in-process → .NET-module → OpenMetadata-feed → gateway op verzoek | accepted |
-
-## Nummering
-
-Deze reeks staat los van de ADR-reeks over de referentie-applicatie zelf, die begint bij
-[`adr-0001-loose-coupling.md`](../adr-0001-loose-coupling.md). Vandaar de eigen map `fds/`: beide
-reeksen beginnen bij 0001, en de nummers zouden anders botsen.
-
-Nieuwe FDS-ADR: kopieer [`adr/template.md`](adr/template.md), neem het volgende nummer, en open een
-pull request.
@@ -1,42 +0,0 @@
-# ADR-0001: Anti-Corruption Layer op elke registergrens
-
- **Status:** accepted
- **Datum:** 2026-06-13
- **Deciders:** Lab Circle (Build, Lead Link)
- **Vervangt / vervangen door:** —
-
-## Context
-
-De applicatie bevraagt meerdere registers: BRP, NHR/KVK, en ZGW via OpenZaak. Hun vocabulaires en
-schema's verschillen van elkaar en van ons domein. Zij veranderen ook zelf mee met de FDS-standaarden.
-
-Lekt registervocabulaire het domeinmodel in, dan werkt elke wijziging aan de registerzijde door in de
-bedrijfslogica. Het domein wordt dan een lappendeken van vreemde begrippen in plaats van ubiquitous
-language.
-
-## Besluit
-
-Elk register is bereikbaar via een Anti-Corruption Layer: **één adapter per register**, die een
-**port** vervult die het domein definieert.
-
-Adapters doen alleen vertalen en velden versmallen. Zij bevatten geen bedrijfslogica. Het domein
-spreekt `Persoon` en `Organisatie`, en nooit veldnamen uit BRP of NHR.
-
-## Gevolgen
-
-**Positief:** verloop in registers en FDS-standaarden blijft bij de adapter. Het domein blijft stabiel
-en testbaar. Adapters zijn onafhankelijk vervangbaar, en dat is precies wat de FSC-wissel uit
-ADR-0002 goedkoop maakt. Het patroon generaliseert naar een herbruikbare ACL-template per register,
-een Foundations-kandidaat.
-
-**Negatief en kosten:** één vertaalmap per register om te schrijven en te onderhouden, plus een extra
-indirectie die engineers moeten respecteren in plaats van omzeilen.
-
-**Vervolgwerk:** extraheer de ACL-template zodra de tweede adapter bestaat (slice 3).
-
-## Overwogen alternatieven
-
- **Registers direct aanroepen uit de applicatieservices** — afgewezen: dit koppelt bedrijfscode aan
-  registerschema's en aan versies van FDS-standaarden.
- **Eén generieke registeradapter** — afgewezen: registers verschillen genoeg dat een generieke
-  abstractie zou gaan lekken of opzwellen. Adapters per register zijn duidelijker.
@@ -1,44 +0,0 @@
-# ADR-0002: FSC voor connectiviteit tussen organisaties, geen ruwe REST
-
- **Status:** accepted
- **Datum:** 2026-06-13
- **Deciders:** Lab Circle, Upstream Liaison
- **Vervangt / vervangen door:** —
-
-## Context
-
-Registerbevragingen kruisen een organisatiegrens naar systemen van bronhouders met
-persoonsgegevens. Het FDS noemt Federatieve Service Connectiviteit (FSC, de opvolger van NLX) als de
-richting voor connectiviteit: wederzijdse authenticatie op organisatieniveau, autorisatie
-gecontroleerd tegen een contract en gehandhaafd bij de bron, en symmetrische transactielogging.
-
-Een ruwe REST-client met mTLS geeft ons geen van de contractadministratie, delegatie of onafhankelijke
-tweezijdige verantwoording die een FG of auditor nodig heeft.
-
-## Besluit
-
-Het FSC Client-component stuurt alle registerbevragingen via een **FSC outway**, de
-EUPL-referentie-implementatie. De ACL-adapter hangt af van de FSC Client, en niet van een HTTP-client.
-
-FSC-zaken — contracten, identiteiten, delegatie — leven in dit component, achter de Register Port.
-
-## Gevolgen
-
-**Positief:** de autorisatie wordt bij de bron gehandhaafd, en niet op gezag van de aanroeper
-vertrouwd. Onweerlegbaar loggen aan beide uiteinden maakt onafhankelijke afstemming tegen ons LDV-log
-mogelijk. Delegatie wordt expliciet meegedragen. Wij lopen in lijn met de FDS-richting, vóór er een
-verplichting is.
-
-**Negatief en kosten:** FSC is operationeel zwaarder dan een REST-aanroep — beheer van certificaten en
-identiteiten, plus een outway die op De Werf moet draaien. De vergelijking FSC tegenover DSP loopt
-binnen het FDS nog, dus sommige details kunnen schuiven.
-
-**Vervolgwerk:** valideer het contract- en logginggedrag van de huidige fsc-nlx-implementatie
-(slice 2). Herzie dit als het FDS voor DSP kiest; ADR-0001 houdt die wissel beperkt tot één component.
-
-## Overwogen alternatieven
-
- **Ruwe REST met mTLS** — afgewezen: geen contractlaag, geen tweezijdig log, en het wijkt af van het
-  FDS.
- **Wachten tot het FDS FSC tegenover DSP heeft beslist** — afgewezen: de naad uit ADR-0001 laat ons nu
-  adopteren en later aanpassen. Wachten geeft het voordeel van vroege expertise weg.
@@ -1,44 +0,0 @@
-# ADR-0003: Policy-based access control via OPA, FTV-klaar
-
- **Status:** accepted
- **Datum:** 2026-06-13
- **Deciders:** Lab Circle, FG (geconsulteerd)
- **Vervangt / vervangen door:** —
-
-## Context
-
-Elke bevraging van persoonsgegevens uit BRP of NHR is een verwerking die een grondslag en een
-begrensde doelbinding nodig heeft. Toegangsregels moeten handhaafbaar en auditeerbaar zijn, en
-wijzigbaar zonder de bedrijfscode opnieuw uit te rollen.
-
-De Federatieve Toegangsverlening (FTV) van het FDS beweegt naar policy-based access control, maar is
-nog geen afgeronde standaard.
-
-## Besluit
-
-Introduceer een Policy Decision Point met Open Policy Agent (OPA). De applicatieservices roepen de
-PDP aan — via een Authorisation Port en een PDP Client — **vóór elke registerbevraging**, en geven
-rol, doel en grondslag mee.
-
-Policies schrijven wij als code, **geversioneerd in Gitea**, en zij gaan via review naar productie. De
-PDP staat zo gepositioneerd dat wij bij de komst van FTV alleen het policy-dialect opnieuw uitdrukken,
-zonder de architectuurgrens te verplaatsen.
-
-## Gevolgen
-
-**Positief:** doelbinding en grondslag worden gehandhaafd, en niet alleen gedocumenteerd. De FG kan de
-werkelijke regels in versiebeheer lezen, waardoor het verwerkingenregister en de gehandhaafde policy
-naar elkaar toe groeien. Toegangswijzigingen zijn reviewbaar en gedateerd.
-
-**Negatief en kosten:** BRP-autorisatiebesluiten correct modelleren is juridisch werk, geen
-engineering. De PDP maakt de handhaving betrouwbaar, niet de policy juist. Daarnaast komt er een
-component bij om te exploiteren.
-
-**Vervolgwerk:** een promotiepijplijn voor policies in Gitea Actions. Policies opnieuw uitdrukken zodra
-FTV stabiliseert. Een FG-review van de policy-set vóórdat er echte persoonsgegevens in komen.
-
-## Overwogen alternatieven
-
- **Rolcontroles in de applicatiecode** — afgewezen: niet auditeerbaar, niet wijzigbaar zonder deploy,
-  en het verspreidt toegangslogica over de codebase.
- **Wachten op FTV** — afgewezen: de PBAC-vorm is al duidelijk. Nu OPA, later het FTV-dialect.
@@ -1,48 +0,0 @@
-# ADR-0004: Begrensde cache; registers blijven systeem van registratie
-
- **Status:** accepted
- **Datum:** 2026-06-13
- **Deciders:** Lab Circle, FG (geconsulteerd)
- **Vervangt / vervangen door:** —
-
-## Context
-
-*Data bij de bron* verbiedt het behandelen van registerdata als lokale bron van waarheid. Maar BRP of
-NHR bij elke interactie bevragen is onpraktisch en vergroot de blootstelling.
-
-Persoonsgegevens zijn de data die wij het minst willen opbouwen. Een onbegrensde cache wordt stil een
-schaduwregister, met een onbeheerde bewaarverplichting als gevolg.
-
-## Besluit
-
-Een **begrensde cache** staat achter een Cache Port, beheerd door een Cache Manager. Vier grenzen
-gelden.
-
-| Grens | Wat die betekent |
-|---|---|
-| **Tijd** | Een TTL die aan het doel hangt |
-| **Omvang** | Alleen de werkset van een actieve zaak |
-| **Gezag** | Antwoordt nooit wat de bron niet zou antwoorden; geen systeem van registratie |
-| **Adresseerbaarheid** | Gesleuteld op subject, zodat verwijderen op verzoek kan |
-
-Purge-triggers: het verstrijken van de TTL, het sluiten van de zaak, en een verwijderingsverzoek.
-
-## Gevolgen
-
-**Positief:** de prestaties van een lokale kopie, zonder een onbevoegd register te worden. Bewaartermijn
-en het recht op verwijdering zijn echte operaties, geen hoop. Dit is consistent met zowel
-AVG-dataminimalisatie als FDS-data-bij-de-bron.
-
-**Negatief en kosten:** de mapping van doel naar TTL is een beleidsbesluit, samen met de FG en de
-autorisatievoorwaarden, en geen engineeringconstante. Die is dus makkelijk fout te krijgen. Daarnaast
-komt de complexiteit van cache-invalidatie erbij.
-
-**Vervolgwerk:** definieer het beleid voor doel naar TTL met de FG. Maak een toestandsdiagram voor de
-levensloop van een cache-entry. Documenteer de aanvaardbare veroudering per register.
-
-## Overwogen alternatieven
-
- **Geen cache; altijd de bron bevragen** — afgewezen: onpraktische latency en belasting, en meer
-  blootstelling per aanroep.
- **Een onbegrensde of algemene cache** — afgewezen: die wordt een schaduwregister, precies de
-  faalvorm waar de AVG en het FDS beide tegen duwen.
@@ -1,42 +0,0 @@
-# ADR-0005: Verwerkingenlog via event-emissie, in lijn met LDV
-
- **Status:** accepted
- **Datum:** 2026-06-13
- **Deciders:** Lab Circle, FG (geconsulteerd)
- **Vervangt / vervangen door:** —
-
-## Context
-
-AVG art. 30 vereist een register van verwerkingsactiviteiten. De FDS-bouwsteen Logboek
-Dataverwerkingen (LDV) wijst naar een gestandaardiseerd verwerkingslog dat de burger kan bevragen.
-
-Database-CDC met Debezium legt *datawijzigingen* vast, en niet *verwerkingsgebeurtenissen met
-doelbinding*. Het is dus geen verwerkingenlog.
-
-## Besluit
-
-Elke registeradapter stuurt een **verwerkingsactiviteit-event** naar een eigen Redpanda-topic, via een
-Verwerking Port en een LDV Emitter. Het event bevat: subjectcategorie, register, velden, doel en
-doelbinding, grondslag, bevragende rol, en tijdstempel. **Nooit de opgehaalde waarden.**
-
-Een projectie maakt het log bevraagbaar. De emissie is asynchroon, maar niet over te slaan: de adapter
-die de Register Port vervult, is dezelfde code die het event uitstuurt.
-
-## Gevolgen
-
-**Positief:** het spoor voor art. 30 en LDV ontstaat als neveneffect van de bevraging, dus het kan niet
-uit de pas lopen met de werkelijkheid. Het is af te stemmen tegen de tweezijdige logs van FSC
-(ADR-0002). Het is onderscheidend in een tender.
-
-**Negatief en kosten:** een topic en een projectie om te exploiteren. Het ontsluiten van het log naar
-de burger valt buiten de huidige scope; wij produceren het log. Het eventschema vraagt governance.
-
-**Vervolgwerk:** definieer het schema van het verwerkingsevent. Bouw de bevraagbare projectie. Sluit
-aan op de LDV-standaard zodra die volwassen wordt; dit is een upstream-kandidaat.
-
-## Overwogen alternatieven
-
- **Debezium-CDC hergebruiken als log** — afgewezen: dat legt datawijzigingen vast, en geen verwerking
-  met doelbinding. Verkeerde semantiek.
- **Synchroon loggen in het aanroeppad** — afgewezen: dat koppelt de latency van de bevraging aan het
-  log. Asynchroon maar niet over te slaan geeft zowel snelheid als garantie.
@@ -1,68 +0,0 @@
-# ADR-0006: Modulegrens en hergebruikstrategie voor de governed-access spine
-
- **Status:** accepted
- **Datum:** 2026-06-13
- **Deciders:** Lab Circle (Lead Link, Build, Upstream Liaison)
- **Vervangt / vervangen door:** —
-
-## Context
-
-De compliance-spine uit slice 1 bestaat uit de PDP-controle (ADR-0003), gegoverneerd uitgaand verkeer
-via FSC (ADR-0002), emissie van het verwerkingenlog (ADR-0005), en de begrensde cache (ADR-0004),
-allemaal achter ports (ADR-0001). Die spine is mogelijk breder herbruikbaar dan alleen in de
-referentie-applicatie.
-
-Er spelen twee hergebruikvragen: welke verpakkingsvorm kiezen wij, en hoe verhoudt de spine zich tot
-andere omgevingen zoals het OpenMetadata-datagovernanceproject?
-
-Twee verduidelijkingen bepalen het besluit.
-
-1. **OpenMetadata is geen afnemer.** In het datagovernanceproject is het de catalogus- en
-   lineage-laag over (synthetische) data. Het bevraagt geen BRP of NHR. FSC of de begrensde cache
-   daarin inbouwen zou zinloos zijn. De juiste aansluiting is **integratie van de output van de
-   spine**, en niet het inbouwen van de spine.
-2. **FSC en de begrensde cache zijn zaken die alleen een afnemer aangaan.** "Maak het herbruikbaar"
-   mag deze niet uitsmeren over componenten die geen registerdata bevragen.
-
-Nu al een taalonafhankelijke gateway bouwen — vóórdat er een tweede, niet-.NET afnemer bestaat — zou
-de valkuil van speculatieve architectuur herhalen, die wij voor de capability-laag al hebben
-afgewezen.
-
-## Besluit
-
-Wij nemen een **vraaggestuurde reeks van vier stappen** aan. Elke stap hangt af van echte behoefte, en
-niet van verwachte behoefte.
-
-| Stap | Wat | Wanneer |
-|---|---|---|
-| 1 | **In-process bewijzen.** Bouw de spine als gewone componenten achter ports, binnen de .NET register-applicatie. Nog geen extractie. Doel: de compliance-invarianten één keer echt valideren. | Slice 1 |
-| 2 | **Extraheren als .NET-module.** Zodra een tweede .NET-afnemer in zicht is, haal de spine eruit als een geversioneerde .NET-library of SDK. Dit is de ACL-template-extractie die het charter al plant. Herbruikbaar voor .NET-afnemers, en dat is genoeg voor register-reference en zijn broertjes. | Slice 3 |
-| 3 | **De feed LDV naar OpenMetadata aansluiten.** Route verwerkingsevents uit de LDV-emitter naar OpenMetadata als access- en usage-metadata bij het geclassificeerde asset: wie las welk persoonsgegevensveld, met welk doel, hoe vaak. Optioneel laten classificatietags uit OpenMetadata terugstromen om veldminimalisatie in de ACL aan te sturen. Dit is de concrete brug tussen beide anchor-projecten: integratie, geen inbouw. | Na stap 2 |
-| 4 | **Alleen op verzoek een taalonafhankelijke gateway bouwen.** Heeft een echte niet-.NET afnemer gegoverneerde registertoegang nodig, verpak de spine dan als zelfstandige sidecar of proxy met een dunne lokale API, met PDP, FSC-egress en LDV erachter. Niet eerder. | Op verzoek |
-
-## Gevolgen
-
-**Positief:** eigen software blijft minimaal. Hergebruik volgt op validatie in plaats van eraan vooraf
-te gaan. Beide anchor-projecten krijgen een concreet, benoemd integratiepunt (stap 3). Zaken die
-alleen een afnemer aangaan, blijven ingesloten.
-
-**Negatief en kosten:** de .NET-module uit stap 2 dient geen niet-.NET afnemers. Dat aanvaarden wij,
-omdat stap 4 dat geval dekt zodra het echt is. Stap 3 vraagt een afgesproken schema voor het
-verwerkingsevent, stabiel genoeg voor OpenMetadata om te consumeren.
-
-**Vervolgwerk:**
-
-1. Neem stap 3 als expliciet integratiepunt op in beide projectpagina's in het Innovation Lab-repo:
-   `projects/open-register-fd/README.md` en `projects/openmetadata/README.md`.
-2. Herzie de trigger van stap 4 bij elke portfolio-review. Bouw niet vooruit.
-3. Regel governance op het schema van het verwerkingsevent; dat is een gedeelde afhankelijkheid van
-   stap 1 en stap 3.
-
-## Overwogen alternatieven
-
- **De taalonafhankelijke gateway vooraf bouwen** — afgewezen: speculatieve architectuur voordat er een
-  tweede afnemer bestaat. De latency en de operationele kosten zijn niet te rechtvaardigen.
- **De spine in OpenMetadata inbouwen** — afgewezen: OpenMetadata is geen afnemer. Dit is een
-  categoriefout.
- **De spine permanent in-process houden, zonder extractie** — afgewezen: dat geeft het hergebruik
-  tussen projecten en applicaties weg, en dat is een kerndoel van de Open Register-inzet.
@@ -1,27 +0,0 @@
-# ADR-NNNN: <titel>
-
- **Status:** proposed
- **Datum:** JJJJ-MM-DD
- **Deciders:** <rollen>
- **Vervangt / vervangen door:** —
-
-## Context
-
-<De krachten die spelen: het probleem, de beperkingen, de FDS- en AVG-drijfveren. Waarom er nu een
-besluit nodig is.>
-
-## Besluit
-
-<De keuze, eenvoudig gesteld.>
-
-## Gevolgen
-
-**Positief:** <wat dit oplevert>
-
-**Negatief en kosten:** <wat het kost, en wat wij aanvaarden>
-
-**Vervolgwerk:** <welk werk dit oproept>
-
-## Overwogen alternatieven
-
-<De afgewezen opties, en waarom.>
@@ -1,127 +0,0 @@
-# C4-componentview — register-applicatie en capability-laag
-
-> Niveau 3, de componentview. Deze view zoomt in op de container van de .NET register-applicatie uit
-> het L2-containerdiagram. Zij verbindt het geheel op componentniveau — domein, ports, adapters en de
-> FDS-capability-componenten — en toont waar elk onderdeel externe tooling raakt.
->
-> De hexagonale structuur is expliciet: het domein hangt alleen af van **ports** (interfaces). Elke
-> concrete capability is een **adapter** die aan een port is gebonden.
->
-> De containerview (L2), de blauwdruk en de privacy-datastroomviews staan in het Innovation Lab-repo,
-> `Respellion/innovation-lab`, onder `projects/open-register-fd/`.
-
-```mermaid
-C4Component
-    title Componentview — register-applicatie (.NET) en de FDS-capability-laag
-
-    Person(user, "Behandelaar", "Behandelt zaken")
-    Container(spa, "Frontend", "Angular + NL Design System", "Zaakinterface")
-
-    Container_Boundary(app, "Register-applicatie (.NET, hexagonaal)") {
-        Component(api, "API / application services", ".NET", "Orkestreert use cases; verklaart doelbinding per vraag")
-        Component(domain, "Domeinmodel", ".NET / DDD", "Ubiquitous language; geen registervocabulaire")
-
-        Component(portReg, "Register Port", "interface", "De vraag van het domein: Personen / Organisaties")
-        Component(portPol, "Authorisation Port", "interface", "mag-deze-verwerking-doorgaan?")
-        Component(portLog, "Verwerking Port", "interface", "leg de verwerkingsgebeurtenis vast")
-        Component(portTm, "Terugmelding Port", "interface", "meld een vermoedelijke fout")
-        Component(portCache, "Cache Port", "interface", "doelgebonden lezen, schrijven en verwijderen")
-
-        Component(aclBrp, "BRP-adapter", ".NET", "Vertaalt domein<->BRP; minimale velden")
-        Component(aclKvk, "NHR/KVK-adapter", ".NET", "Vertaalt domein<->NHR; UBO-bewust")
-        Component(pdpClient, "PDP Client", ".NET -> OPA", "Roept de policy engine; geeft doel en grondslag mee")
-        Component(ldvEmit, "LDV Emitter", ".NET", "Bouwt het verwerkingsevent; publiceert naar Redpanda")
-        Component(fscClient, "FSC Client", ".NET", "Stuurt contractuele aanroepen via de outway")
-        Component(cacheMgr, "Cache Manager", ".NET", "TTL en verwijderen op subjectsleutel")
-        Component(tmHandler, "Terugmelding Handler", ".NET -> Flowable", "Start het terugmeldproces")
-        Component(procClient, "Process Client", ".NET -> Flowable", "Uitvoering van BPMN en DMN")
-    }
-
-    System_Ext(opa, "OPA (PDP)", "Policies geversioneerd in Gitea")
-    System_Ext(fsc, "FSC Outway", "EUPL-referentie-implementatie")
-    System_Ext(flowable, "Flowable", "BPMN + DMN")
-    ContainerDb_Ext(cache, "Begrensde cache", "PostgreSQL")
-    System_Ext(redpanda, "Redpanda", "LDV-topic + CDC")
-    System_Ext(brp, "BRP", "via FSC inway")
-    System_Ext(kvk, "NHR / KVK", "via FSC inway")
-    System_Ext(kanidm, "Kanidm", "OIDC")
-
-    Rel(user, spa, "Gebruikt")
-    Rel(spa, api, "REST/JSON")
-    Rel(kanidm, api, "OIDC", "authenticatie")
-    Rel(api, domain, "Roept aan")
-    Rel(api, portPol, "Controleert vóór de bevraging")
-    Rel(api, portReg, "Vraagt data")
-    Rel(api, portTm, "Dient melding in")
-    Rel(api, procClient, "Voert proces uit")
-
-    Rel(portPol, pdpClient, "gebonden aan")
-    Rel(pdpClient, opa, "besluitverzoek")
-
-    Rel(portReg, aclBrp, "gebonden aan")
-    Rel(portReg, aclKvk, "gebonden aan")
-    Rel(aclBrp, fscClient, "via")
-    Rel(aclKvk, fscClient, "via")
-    Rel(aclBrp, portLog, "stuurt event")
-    Rel(aclKvk, portLog, "stuurt event")
-    Rel(aclBrp, portCache, "leest en schrijft")
-    Rel(aclKvk, portCache, "leest en schrijft")
-    Rel(fscClient, fsc, "contractuele aanroep")
-    Rel(fsc, brp, "mTLS + contract")
-    Rel(fsc, kvk, "mTLS + contract")
-
-    Rel(portLog, ldvEmit, "gebonden aan")
-    Rel(ldvEmit, redpanda, "publiceert")
-    Rel(portCache, cacheMgr, "gebonden aan")
-    Rel(cacheMgr, cache, "slaat op")
-    Rel(portTm, tmHandler, "gebonden aan")
-    Rel(tmHandler, flowable, "start proces")
-    Rel(procClient, flowable, "voert uit")
-```
-
-## Hoe je dit leest
-
-1. **De ports zijn de naad.** Het domein en de application services hangen af van de vijf interfaces,
-   en nooit van adapters. FSC wisselen voor DSP, of OPA voor de latere FTV-client, verandert een
-   adapter — geen port, en niet het domein. Dit is de clock-speed boundary, concreet gemaakt.
-2. **De compliance-componenten zijn adapters, geen domeinlogica.** De PDP-client, de LDV-emitter, de
-   FSC-client en de cache manager staan allemaal aan de adapterzijde. Een bevraging kan er fysiek niet
-   langs, omdat de adapter die de Register Port vervult dezelfde code is die het LDV-event uitstuurt
-   en via FSC routeert.
-3. **Slechts twee componenten raken de registers**: de BRP-adapter en de NHR/KVK-adapter. Beide
-   bereiken ze uitsluitend via de FSC-client. Er is geen vierde pad.
-
-## Componenten tegenover verplichtingen
-
-| Component | Omvang eigen bouw | Verplichting die het afdekt |
-|---|---|---|
-| Domeinmodel | het product | correctheid van de bedrijfsregels |
-| BRP- en NHR-adapters | dun | dataminimalisatie: vertalen en velden versmallen |
-| PDP Client | klein | handhaven van grondslag en doelbinding |
-| LDV Emitter | klein | verwerkingenlog (AVG art. 30 en LDV) |
-| FSC Client | klein | geautoriseerde, gelogde connectiviteit |
-| Cache Manager | klein | grenzen aan bewaring, en verwijdering |
-| Terugmelding Handler | klein | de terugmeldplicht van de afnemer |
-
---
-
-## Aanvullende views die voor engineers waarde hebben
-
-De diagrammen tot hier verklaren *structuur* en *compliance-intentie*. Engineers die dit bouwen,
-hebben er nog een aantal nodig. Wij tekenen geen view voordat er iets echt is om te beschrijven, dus
-elke regel noemt de trigger.
-
-| # | View | Wat het toevoegt | Trigger |
-|---|---|---|---|
-| 1 | **Deploymentview** (C4 deployment, topologie) | Waar elke container op De Werf draait: k3s-namespaces, welke services sidecar zijn en welke een eigen pod (is OPA een sidecar of centraal? waar eindigt de FSC outway?), netwerkpolicies tussen de vlakken van de vertrouwensgrens, en beheer van secrets en mTLS-certificaten voor FSC. Hier worden de privacy*grenzen* echte firewall- en netwerkregels. | Vóór de eerste deploy met meerdere services. **Hoogste waarde als volgende.** |
-| 2 | **Sequences voor de niet-gelukkige paden** | Wij hebben het gelukkige pad. Engineers hebben de lastige nodig: PDP-*deny* midden in een transactie, een verlopen of ingetrokken FSC-contract, een register-timeout terwijl er een verouderde cache-entry ligt, en een gedeeltelijk NHR-antwoord waarbij een UBO-veld is achtergehouden. Dit bepaalt de foutafhandeling, en hier verstoppen de compliance-randgevallen zich. | Direct na slice 1. |
-| 3 | **Domeinmodel en ERD** | De bounded contexts en aggregates in het domein, plus het cacheschema: welke persoonsgegevens blijven staan, op welke sleutel, en met welke purge-kolom. Dit is tegelijk het artefact dat de FG beoordeelt voor bewaartermijnen. | Zodra het domein in slice 1 stabiliseert. |
-| 4 | **Dataclassificatie- en catalogusview** | Elk veld dat een grens kruist, getagd — persoonsgegeven? bijzondere categorie? UBO-beperkt? — en gemapt op zijn classificatie in OpenMetadata. Dit stuurt de GDPR-scrubbingregels en de lineage-tags. | Beter *uit* OpenMetadata gegenereerd zodra die gevuld is, dan met de hand getekend. |
-| 5 | **Toestandsdiagram: levensloop van een cache-entry** | `fetched` → `valid` (binnen TTL) → `stale` → `purged` (TTL verstreken \| zaak gesloten \| verwijderingsverzoek). Klein, maar het pint de bewaarsemantiek vast die "begrensde cache" nu alleen in prose beschrijft. | Samen met ADR-0004-vervolgwerk. |
-| 6 | **BPMN-view: de terugmelding-workflow** | Het Flowable-proces zelf: ingediend → verstuurd naar bronhouder → bevestigd → opgelost of afgewezen. Dit is uitvoerbaar BPMN, dus het diagram en de implementatie zijn hetzelfde artefact. | Wanneer de terugmelding-slice start. |
-| 7 | **Threat model en vertrouwensgrensview** (STRIDE-stijl) | Dreigingen over de vertrouwensgrens leggen: tokendiefstal, cache poisoning, replay tegen FSC, policy bypass, en manipulatie van logs. Past natuurlijk bij de FSC-zoom, en is het anker van het securitygesprek. | Vóór het verwerken van echte persoonsgegevens. |
-| 8 | **CI/CD- en policy-promotieview** | Hoe OPA-policies en BPMN/DMN-modellen van een pull request naar draaiende configuratie gaan. "Toegangsbeheer is configuratie in Gitea" geldt alleen als er een pijplijn is die review en promotie handhaaft. | Samen met het vervolgwerk uit ADR-0003. |
-
-**Voorstel voor de volgende twee.** De **deploymentview**, omdat die de privacygrenzen omzet in
-handhaafbare netwerkpolicy. En de **sequences voor de niet-gelukkige paden**, omdat compliance daar
-werkelijk breekt.
@@ -1,103 +0,0 @@
-# POC-voorstel — slice 1: walking skeleton (één register, gegoverneerde bevraging)
-
-> Klaar om in een `poc-voorstel`-issue te plakken, met de labels `build` en `poc`. Dit is het bouwbare
-> eerste increment dat de architectuurdocumenten beschrijven. Het bewijst met opzet de
-> *compliance-spine* end-to-end op de dunst mogelijke functionaliteit.
-
-## Probleem en strategische vraag
-
-Kunnen wij een registerbevraging demonstreren die *structureel* gegoverneerd is — onmogelijk uit te
-voeren zonder gehandhaafde grondslag en een automatische regel in het verwerkingenlog — op onze
-soevereine stack?
-
-Dit is de geloofwaardigheidstoets achter de hele Open Register-inzet (slice 1 van het charter) en
-achter de FDS gap-analyse.
-
-## Hypothese
-
-Wij verwachten dat het doorverbinden van één registerbevraging door de volledige capability-spine —
-Register Port → ACL-adapter → PDP-controle → FSC-aanroep → LDV-emissie → begrensde cache — de claim
-"compliance is structureel" bewijst.
-
-Wij weten dat wij het goed hebben als een geautomatiseerde test aantoont dat een bevraging **niet** kan
-voltooien als de PDP weigert, en **altijd** een LDV-event oplevert als de PDP toestaat.
-
-## Scope ter grootte van één blok
-
-**Wel in scope**
-
-| Onderdeel | Wat |
-|---|---|
-| Register | **NHR/KVK**, basisgegevens over onderneming en bestuurder. Gekozen boven BRP; zie de slotnotitie. |
-| Use case | Geef bij een KVK-nummer de geregistreerde organisatie terug aan het domein, voor één verklaard doel. |
-| Ports | De vijf ports als interface. Concrete adapters: NHR-ACL, PDP-client (OPA), FSC-client met sandbox- of test-outway, LDV-emitter (Redpanda-topic), en cache manager (PostgreSQL met TTL). |
-| Policy | OPA draait met één handgeschreven voorbeeldpolicy in Gitea: één allow-regel en één deny-geval. |
-| Log | Verwerkingsevent-schema v0 plus een minimale bevraagbare projectie; een tabelweergave is genoeg. |
-| Tests | Tests die de twee compliance-invarianten vastleggen: deny blokkeert, allow logt. |
-
-**Niet in scope** — even belangrijk om op te schrijven.
-
-1. Afgewerkte interface of NL Design System-schermen, verder dan een dev-harness.
-2. BRP en paden met veel persoonsgegevens. Die gaan naar slice 2, met een door de FG beoordeelde
-   policy.
-3. UBO-data. Het regime van beperkte toegankelijkheid valt buiten deze slice.
-4. De terugmelding-workflow (latere slice), DCAT-export, en Superset-dashboards.
-5. Echte register-endpoints. Alleen sandbox en stubs.
-
-## Definition of Done
-
- [ ] Een bevraging op KVK-nummer geeft een domein-`Organisatie` terug via de NHR-ACL-adapter, zonder
-      registervocabulaire in het domein (ADR-0001).
- [ ] De aanroep loopt via de FSC-client naar een sandbox-outway, en niet via een ruwe HTTP-client
-      (ADR-0002).
- [ ] Er vindt geen bevraging plaats tenzij de PDP allow teruggeeft voor de combinatie rol, doel en
-      grondslag (ADR-0003).
- [ ] Elke toegestane bevraging stuurt precies één verwerkingsevent naar Redpanda, bevraagbaar in de
-      projectie, zonder opgehaalde waarden (ADR-0005).
- [ ] Cache-entries dragen een TTL en een subjectsleutel; een purge-aanroep verwijdert ze (ADR-0004).
- [ ] **De tests op de compliance-invarianten slagen in CI:** (a) PDP-deny betekent geen FSC-aanroep;
-      (b) PDP-allow betekent precies één LDV-event; (c) te ruim gevraagde velden bereiken het domein
-      nooit.
- [ ] Het geheel draait lokaal uit een gedocumenteerd `compose`- of k3s-manifest met stubs, zonder
-      echte registertoegang.
- [ ] ADR-0001 tot en met ADR-0005 zijn vanuit de code gelinkt. Eén nieuwe ADR als er in slice 1 een
-      besluit ontstaat.
-
-## Acceptatiedemo (bewijs voor de week-3-toets)
-
-Live: een geslaagde bevraging plus de bijbehorende LDV-regel. Zet daarna de policy op deny en toon
-dezelfde bevraging geweigerd, zonder registeraanroep en zonder data.
-
-Dat contrast *is* de demo.
-
-## Ontvangende Delivery Circle (voorlopig)
-
-De register-reference Delivery Circle. De Handoff-ontvanger krijgt bij de kickoff een naam.
-
-Waarschijnlijke adoptie: de capability-spine wordt het herbruikbare substraat voor de
-register-reference-applicatie.
-
-## Upstream-kandidaten
-
-| Project | Wat wij kunnen bijdragen |
-|---|---|
-| fsc-nlx | Ergonomie van de sandbox en testomgeving, plus documentatie |
-| OPA | Policy-patronen voor het modelleren van Nederlandse grondslagen |
-| OpenMetadata | Later een DCAT-AP-NL exporter; dit verbindt het OpenMetadata-project |
-
-## AVG- en soevereiniteitsoverwegingen
-
-Alleen NHR-basisgegevens, over onderneming en bestuurder, en in slice 1 **gestubd**. Er worden geen
-echte persoonsgegevens verwerkt.
-
-Een FG-review is een voorwaarde voor slice 2, met echte data en BRP. Alle componenten draaien
-zelfgehost op De Werf; OPA-policies en BPMN staan in Gitea.
-
-## Slotnotitie: waarom NHR vóór BRP voor het skeleton
-
-Beide registers bevatten persoonsgegevens, dus geen van beide is "gratis". NHR-basisgegevens over
-onderneming en bestuurder zijn echter minder gevoelig dan BRP-gegevens over inwoners, en er is een
-duidelijker verhaal rond een publieke sandbox.
-
-Zo bewijst slice 1 het *mechanisme*, voordat slice 2 BRP oppakt onder een door de FG beoordeelde
-policy. UBO-data blijft buiten scope tot het toegangsregime is gemodelleerd.
@@ -9,9 +9,6 @@ should teach.
 - **[Product Requirements](PRD.md)** — what we're building and why.
 - **[ADR-0001: Loose coupling](architecture/adr-0001-loose-coupling.md)** — the
  non-negotiable integration stance; the template for future ADRs.
- **[FDS architecture](architecture/fds/README.md)** — participating in the Federatief
-  Datastelsel as an afnemer: ADR-0001…0006, the L3 component view, the slice-1 proposal.
-  In Dutch; the strategic framing lives in `Respellion/innovation-lab`.
 - **[Working in Gitea](gitea-workflow.md)** — issues, milestones, branches, PRs.
 - **[CI runbook](runbooks/ci.md)** — the pipeline and the `make ci` local gate.

@@ -1,11 +1,9 @@
 # CI runbook — Gitea Actions

-> **Status: no runner yet → run CI locally with `make ci`.** The workflow
-> `.gitea/workflows/ci.yaml` is in place, but the pipeline cannot go green until a
-> self-hosted `respellion-linux` runner is registered against the Gitea instance.
-> Until then, **`make ci` is the gate** — it runs the exact same checks locally
-> (the workflow calls the same `make` targets). Issue **#30 (S-00-c)** stays open
-> until CI is verified green on a runner.
+> **Status: active.** The workflow `.gitea/workflows/ci.yaml` runs on Gitea's
+> hosted `ubuntu-latest` runner — no self-hosted runner required.
+> **`make ci` is still the local gate** — it runs the exact same checks
+> (the workflow calls the same `make` targets).

 ## The pipeline

@@ -18,19 +16,81 @@ and CI cannot drift:
 | `lint` | `make lint` → `dotnet format … --verify-no-changes` | .NET 10 SDK |
 | `build` | `make build` → `dotnet build … -c Release` | .NET 10 SDK |
 | `unit` | `make unit` → `dotnet test … -c Release` | .NET 10 SDK |
-| `compose-smoke` | `make smoke` → compose up `--wait` → `curl /health` → `down` | container engine + compose v2 |
+| `mutation` | `make mutation` → `dotnet tool restore` → `dotnet stryker` (ACL); uploads the HTML report as an artifact | .NET 10 SDK |
+| `compose-smoke` | `make smoke` → seed config volumes → `up -d` (full stack) → `up --wait` durable services → `down` | container engine + compose v2 |

 All `uses:` references are absolute, tag-pinned URLs (`https://github.com/actions/checkout@v4`,
 `https://github.com/actions/setup-dotnet@v4`) per CLAUDE.md §8.7 and §15 — Gitea
 Actions resolves them from GitHub.

+> **`compose-smoke` runs on a containerized runner.** Workspace bind mounts do
+> **not** reach the sibling containers Compose starts, so config/assets are
+> streamed into external named volumes via `docker cp` (`infra/seed-config.sh`),
+> and the upstream images are used verbatim (no build). If you add a service that
+> needs a repo file at runtime, seed it the same way — don't bind-mount it. Note:
+> bare `docker compose up` no longer self-seeds; use `make up`. See
+> [gitea-actions-gotchas.md](gitea-actions-gotchas.md).
+
+## Mutation testing (the ratchet)
+
+The `mutation` job enforces test *strength*, not just coverage (CLAUDE.md §5).
+[Stryker.NET](https://stryker-mutator.io/docs/stryker-net/) is pinned as a local
+dotnet tool (`.config/dotnet-tools.json`), so it runs identically locally and in CI:
+
+```bash
+make mutation     # dotnet tool restore + dotnet stryker on the ACL
+```
+
+Config lives in [`services/acl/stryker-config.json`](../../services/acl/stryker-config.json).
+It runs in **solution mode** against `Acl.slnx`, mutating the two projects under test
+(`Acl.Application`, `Acl.Infrastructure`); `Acl.Api` has no tests and is skipped.
+
+**Baseline (the ratchet):** the ACL is the first service with branching logic, so it
+sets the repo-wide baseline. Observed score **95%**; enforced `break` threshold **90%**
+(one-mutant headroom over the ~20-mutant surface). Stryker exits non-zero — failing the
+job — when the score drops below `break`. Per §5 the baseline only moves **up**, and only
+as a slice's stated outcome; never lower it. New services add their own mutation run as
+they gain logic.
+
+The HTML report is written to `services/acl/StrykerOutput/<timestamp>/reports/` (git-ignored);
+open it to see survived vs. killed mutants.
+
+In CI the `mutation` job publishes that report as the **`acl-mutation-report`** artifact
+(download it from the run's summary page). The upload step uses `if: always()`, so the
+report is available even when the ratchet *fails* — which is exactly when you want to inspect
+the survivors. It is the repo's first use of `actions/upload-artifact`, pinned to **`@v3`**:
+`@v4` refuses to run on Gitea (its `@actions/artifact` v2 library blocks any non-github.com
+server as "GHES"), while `@v3` speaks the artifact protocol Gitea implements. See
+[gitea-actions-gotchas.md §4](gitea-actions-gotchas.md) (§15).
+
+## Running the stack locally without `make` (Windows / Docker Desktop)
+
+`make` and the bash helpers assume a Unix shell. To bring the whole stack up on a
+machine without them (e.g. Windows + Docker Desktop), use the **local compose
+file**, which bind-mounts the config instead of seeding volumes — so it needs no
+`make`, no seed step, and no bash:
+
+```bash
+docker compose -f infra/docker-compose.local.yml up -d --build          # any engine
+docker compose -f infra/docker-compose.local.yml up -d --build --wait    # Docker Desktop (Compose v2)
+docker compose -f infra/docker-compose.local.yml down --volumes
+```
+
+On Linux/macOS the same thing is wrapped as `make local` / `make local-down`.
+
+`infra/docker-compose.local.yml` mirrors the canonical `infra/docker-compose.yml`
+but swaps the external config volumes for bind mounts — valid locally because a
+local daemon can see the working directory (the seed/volume dance only exists for
+the containerized CI runner). Keep the two files in sync.
+
 ## Running CI locally (`make ci`)

 Until the runner exists, run the full pipeline yourself before pushing:

 ```bash
-make ci          # lint + build + unit + smoke — what the pipeline runs
+make ci          # lint + build + unit + mutation + smoke — what the pipeline runs
 make lint        # or a single stage
+make mutation    # Stryker.NET ratchet on the ACL
 make smoke       # compose up --wait, curl /health, tear down
 ```

@@ -49,56 +109,26 @@ The Makefile auto-points `DOCKER_HOST` at `/run/user/$(id -u)/podman/podman.sock
 when that socket exists and `DOCKER_HOST` is unset, so `make smoke` "just works"
 locally while leaving real Docker hosts / CI runners untouched.

-## Runner: `respellion-linux`
+## Runner: `ubuntu-latest`

-The single self-hosted runner label this repo targets is **`respellion-linux`**
-(declared here per §15). It is intended to run **co-located on the Gitea server**
-(`git.labs.respellion.tech` / `46.224.220.37`) so CI is durable and independent of
-any developer machine.
+All jobs run on Gitea's hosted **`ubuntu-latest`** runner — no self-hosted runner
+setup is required. The hosted runner ships with Docker and Docker Compose v2, so
+`make smoke` (`docker compose … up --wait`) works without extra configuration.

-### Host prerequisites
-
-The runner executes jobs in **host mode** (see registration below), so the host
-must have, on `PATH`:
-
- .NET 10 SDK (or let `setup-dotnet` install it into the runner tool cache)
- A container engine with Compose v2 — Docker, or Podman with the Docker-compatible
-  socket and the `docker-compose` provider (as configured on the dev box)
- `curl`
-
-### Install & register `act_runner` (on the Gitea server)
+If Gitea's hosted runners are unavailable and a self-hosted fallback is needed,
+register an `act_runner` with the `ubuntu-latest` label:

 ```bash
-# 1. Install the binary (pick the version matching the Gitea release line)
 VER=0.2.11
 curl -fsSL -o /usr/local/bin/act_runner \
  "https://dl.gitea.com/act_runner/${VER}/act_runner-${VER}-linux-amd64"
 chmod +x /usr/local/bin/act_runner

-# 2. Obtain a registration token from the Gitea UI:
-#    Site Administration → Actions → Runners → "Create new Runner"  (instance-level)
-#    (or Repo → Settings → Actions → Runners for a repo-scoped runner)
-
-# 3. Register with the respellion-linux label in HOST execution mode.
-#    The ":host" suffix means jobs run directly on the host shell, so
-#    `docker compose` in compose-smoke uses the host engine (no docker-in-docker).
 act_runner register --no-interactive \
  --instance https://git.labs.respellion.tech \
  --token <REGISTRATION_TOKEN> \
  --name respellion-ci-1 \
-  --labels "respellion-linux:host"
+  --labels "ubuntu-latest:docker://node:20-bookworm"

-# 4. Run it (foreground to verify, then install as a systemd service)
 act_runner daemon
 ```
-
-Verify in the Gitea UI (Actions → Runners) that `respellion-ci-1` shows **Idle**,
-then re-run the `CI` workflow; all four jobs should pass.
-
-## Security note
-
-A self-hosted runner in **host mode** executes workflow code directly on the Gitea
-server host. Anyone who can push a workflow can run code there. This is acceptable
-for a **private lab** instance with trusted contributors. For anything
-internet-facing, switch to container/VM isolation (`--labels "respellion-linux:docker://..."`)
-or a dedicated runner host, and gate workflow runs on approval for outside PRs.
@@ -0,0 +1,126 @@
+# Gitea Actions gotchas
+
+How our CI (Gitea Actions on the hosted **`ubuntu-latest`** runner) differs from a
+local run, and the workarounds in this repo. Referenced by `CLAUDE.md` §8.7/§15.
+
+**One root cause sits under most of this:** the runner executes the job **inside a
+container**, so when a step runs `docker compose up`, Compose starts the stack as
+**sibling containers** on the host's daemon. Anything that assumes the job and
+those containers share a filesystem — or a `localhost` — breaks.
+
+| Gotcha | Fix | Lives in |
+|---|---|---|
+| Bind-mounted config arrives empty | `docker cp` config into external volumes | `infra/seed-config.sh` |
+| `docker compose up --wait` is unsupported / flaky | poll health with `docker inspect` | `infra/wait-healthy.sh` |
+| `pg_isready` passes before PostGIS is ready | add a `PostGIS_Version()` probe | the db healthchecks |
+| `upload-artifact@v4` fails ("not supported on GHES") | pin `@v3` | `.gitea/workflows/ci.yaml` (`mutation` job) |
+
+---
+
+## 1. Bind mounts don't reach the containers
+
+**Symptom** — green locally, but `compose-smoke` fails with:
+
+```
+oz-init-1 | CommandError: Yaml file `/app/setup_configuration/data.yaml` does not exist.
+```
+
+Migrations run fine; only the step that reads a *mounted* file fails. The same
+trap hits `nrc-init`, `flowable-init`, and `keycloak`.
+
+**Why** — a relative bind mount like `./openzaak/setup_configuration:/app/...` is
+resolved by Compose to a path *inside the job container*
+(`/workspace/.../setup_configuration`). The daemon then looks for that path on
+*its own host*, doesn't find it, and mounts an **empty directory**. (It works on a
+runner that executes jobs on the host — which is why moving to `ubuntu-latest`
+exposed it.)
+
+**Fix** — use the upstream images verbatim (no build) and stream config into
+**external named volumes** with `docker cp`, which copies over the Docker API and
+so works wherever the daemon runs. `infra/seed-config.sh` creates each volume,
+mounts it in a throwaway helper, and copies the files in:
+
+| Asset | Volume | Mounted at |
+|---|---|---|
+| OpenZaak `data.yaml` | `rr-oz-config` | `oz-init:/app/setup_configuration` |
+| Keycloak realms | `rr-kc-realms` | `keycloak:/opt/keycloak/data/import` |
+| `registratie.bpmn` | `rr-fl-bpmn` | `flowable-init:/work` |
+
+The volumes are `external: true` with fixed names, so they resolve identically
+under docker compose and podman-compose. `make` seeds before every `up`; `make
+down` removes them. (Open Notificaties needs nothing — `nrc-init` migrates only.)
+
+**Consequence — bare `docker compose up` can't self-seed external volumes:**
+
+- **CI / Linux / macOS:** `make up` or `make smoke` (seed, then start).
+- **No-make / Windows:** `infra/docker-compose.local.yml` — a twin stack that
+  **bind-mounts** the config instead. Bind mounts are fine *locally* because a
+  local daemon can see your working directory, so
+  `docker compose -f infra/docker-compose.local.yml up -d` just works.
+
+**Why not the obvious alternatives**
+
+- *Bake config into an image* (incl. an inline Dockerfile) — `docker compose up`
+  would then work unaided, but it's a build; we wanted the upstream images as-is.
+- *Compose `configs:` with inline `content`* — Compose writes a client-side temp
+  file and bind-mounts it, hitting the exact same problem.
+- *A host-executing runner* — bind mounts would work with zero seeding, but it
+  reintroduces a self-hosted runner and undoes the move to `ubuntu-latest`.
+
+---
+
+## 2. Readiness: poll health, don't use `--wait`
+
+`docker compose up --wait` looks ideal but fails us three ways:
+
+- **podman-compose doesn't implement it** (`unrecognized arguments: --wait`) — so
+  it would break local dev.
+- A project-wide `--wait` **treats a one-shot exiting `0` as a failure** unless
+  something `depends_on` it with `service_completed_successfully`. `flowable-init`
+  deploys the BPMN and exits with no dependant, so `--wait` fails the moment it
+  does — last line `container infra-flowable-init-1 exited (0)`.
+- The containerized runner **can't reach published host ports**, so an external
+  `curl localhost:8080/health` can't work either.
+
+**Fix** — `infra/wait-healthy.sh` polls each durable service (`openzaak nrc-web
+acl bff`, listed as `WAIT_SVCS` in the `Makefile`) with `docker ps` + `docker
+inspect '{{.State.Health.Status}}'` until it reports `healthy`. It uses only
+primitives both runtimes support, reads the **in-container** healthcheck (no host
+port needed), and ignores the one-shots (they only need to have run).
+`WAIT_TIMEOUT` defaults to 420 s — enough for the cold OpenZaak migrate (~90 s)
+plus app start.
+
+---
+
+## 3. `pg_isready` passes before PostGIS is ready
+
+`pg_isready` succeeds as soon as the TCP port is open — *before* the
+`postgis/postgis` image has finished running `CREATE EXTENSION postgis`. An init
+container that starts migrating in that window can fail on a missing PostGIS. So
+the db healthchecks add a `SELECT PostGIS_Version()` probe, making dependents wait
+for the extension, not just the port.
+
+---
+
+## 4. `actions/upload-artifact@v4` refuses to run on Gitea
+
+**Symptom** — the `mutation` job's `make mutation` step passes (95% score), but the
+upload step right after it fails the job:
+
+```
+::error::@actions/artifact v2.0.0+, upload-artifact@v4+ and download-artifact@v4+
+are not currently supported on GHES.
+❌  Failure - Main https://github.com/actions/upload-artifact@v4
+```
+
+**Why** — `upload-artifact@v4` bundles `@actions/artifact` v2, which inspects the
+server URL and **hard-aborts on anything that isn't `github.com`**, treating Gitea
+as an unsupported GitHub Enterprise Server. The check fires regardless of whether
+the Gitea server can actually store artifacts (1.24+ can). It is the *action*, not
+the server, that refuses.
+
+**Fix** — pin **`actions/upload-artifact@v3`** (and `download-artifact@v3` if ever
+needed). v3 uses the older artifact protocol that Gitea implements, and has no GHES
+guard. Inputs are the same (`name`, `path`, `if-no-files-found`), so it is a drop-in
+swap. Do **not** bump to `@v4` until act_runner advertises github.com-compatible
+artifact support.
@@ -71,5 +71,12 @@ The Makefile auto-points `DOCKER_HOST` at the Podman socket when it exists, so t
  but OZ→NRC delivery wiring + re-enabling lands with **S-06**.
 - **Zaaktype is a concept**, not published (publishing needs roltypen/statustypen/
  resultaattypen — beyond the lean seed). List with `?status=alles`.
- **Image tag.** Currently `openzaak/open-zaak:latest` via `${OPENZAAK_TAG}`; pin to
-  a known-good tag (ADR-0002 follow-up).
+- **Image tag.** Pinned to `openzaak/open-zaak:1.28.2` via `${OPENZAAK_TAG}` (bump
+  deliberately, not via `:latest`).
+- **Config arrives via a volume, not a bind mount.** `setup_configuration/data.yaml`
+  is streamed into the external `rr-oz-config` volume by `infra/seed-config.sh`
+  (`docker cp`) and mounted at `/app/setup_configuration`, so the init container
+  finds it on Gitea's containerized CI runner too (bind mounts don't reach sibling
+  containers there). The image is the upstream `openzaak/open-zaak` verbatim — no
+  build. Run via `make openzaak-up` (seeds first). See
+  [gitea-actions-gotchas.md](gitea-actions-gotchas.md).
@@ -0,0 +1,296 @@
+# LOCAL development stack — runs with a plain `docker compose up`, no make / no
+# seed step / no bash. Use this on a local engine (Docker Desktop on Windows or
+# macOS, or rootless Podman on Linux).
+#
+#   docker compose -f infra/docker-compose.local.yml up -d --build         # podman
+#   docker compose -f infra/docker-compose.local.yml up -d --build --wait  # Docker Desktop
+#   docker compose -f infra/docker-compose.local.yml down --volumes
+#
+# It is identical to infra/docker-compose.yml EXCEPT that the three config inputs
+# (OpenZaak data.yaml, Keycloak realms, Flowable BPMN) are **bind-mounted** from
+# the repo instead of being streamed into external volumes by infra/seed-config.sh.
+# Bind mounts work here because a local daemon can see your working directory —
+# the seed dance only exists for the containerized CI runner, where it can't. See
+# docs/runbooks/gitea-actions-gotchas.md.
+#
+# `infra/docker-compose.yml` remains the CI-canonical stack; keep the two in sync.
+#
+# Port map (host):
+#   8000 OpenZaak · 8001 Open Notificaties · 8080 BFF · 8090 Flowable REST
+#   8100 ACL · 8180 Keycloak   (all admin: admin / admin — dev only)
+
+services:
+
+  # ── OpenZaak (S-01) ──────────────────────────────────────────────────────
+  oz-db:
+    image: docker.io/postgis/postgis:17-3.5
+    environment:
+      POSTGRES_USER: openzaak
+      POSTGRES_PASSWORD: openzaak
+      POSTGRES_DB: openzaak
+    command: postgres -c max_connections=300
+    volumes:
+      - oz-db:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U openzaak -d openzaak && psql -U openzaak -d openzaak -c 'SELECT PostGIS_Version();' -q 2>/dev/null"]
+      interval: 5s
+      timeout: 5s
+      retries: 30
+      start_period: 15s
+    networks: [cg]
+
+  oz-redis:
+    image: docker.io/library/redis:7
+    networks: [cg]
+
+  oz-init:
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-1.28.2}
+    environment: &oz-env
+      DJANGO_SETTINGS_MODULE: openzaak.conf.docker
+      SECRET_KEY: ${OZ_SECRET_KEY:-dev-only-not-for-production}
+      DB_HOST: oz-db
+      DB_NAME: openzaak
+      DB_USER: openzaak
+      DB_PASSWORD: openzaak
+      IS_HTTPS: "no"
+      ALLOWED_HOSTS: "*"
+      CACHE_DEFAULT: oz-redis:6379/0
+      CACHE_AXES: oz-redis:6379/0
+      CELERY_BROKER_URL: redis://oz-redis:6379/1
+      CELERY_RESULT_BACKEND: redis://oz-redis:6379/1
+      DISABLE_2FA: "true"
+      NOTIFICATIONS_DISABLED: "true"
+      OPENZAAK_SUPERUSER_USERNAME: admin
+      DJANGO_SUPERUSER_PASSWORD: admin
+      OPENZAAK_SUPERUSER_EMAIL: admin@localhost
+      RUN_SETUP_CONFIG: "true"
+    command: /setup_configuration.sh
+    # Bind mount (`:z` relabels for SELinux on Linux; a no-op on Docker Desktop).
+    volumes:
+      - ./openzaak/setup_configuration:/app/setup_configuration:ro,z
+    depends_on:
+      oz-db:
+        condition: service_healthy
+      oz-redis:
+        condition: service_started
+    networks: [cg]
+
+  openzaak:
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-1.28.2}
+    environment: *oz-env
+    healthcheck:
+      test: ["CMD", "python", "-c", "import requests,sys; sys.exit(0 if requests.head('http://localhost:8000/admin/').status_code in (200,302) else 1)"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+    ports:
+      - "8000:8000"
+    depends_on:
+      oz-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+  oz-celery:
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-1.28.2}
+    environment: *oz-env
+    command: /celery_worker.sh
+    depends_on:
+      oz-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+  # ── Open Notificaties / NRC (S-01-c) ─────────────────────────────────────
+  nrc-db:
+    image: docker.io/postgis/postgis:17-3.5
+    environment:
+      POSTGRES_USER: opennotificaties
+      POSTGRES_PASSWORD: opennotificaties
+      POSTGRES_DB: opennotificaties
+    command: postgres -c max_connections=300
+    volumes:
+      - nrc-db:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U opennotificaties -d opennotificaties"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    networks: [cg]
+
+  nrc-redis:
+    image: docker.io/library/redis:7
+    networks: [cg]
+
+  nrc-init:
+    # Migrations only (see the canonical compose / ADR-0002); no config needed.
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-1.16.1}
+    environment: &nrc-env
+      DJANGO_SETTINGS_MODULE: nrc.conf.docker
+      SECRET_KEY: ${NRC_SECRET_KEY:-dev-only-not-for-production}
+      DB_HOST: nrc-db
+      DB_NAME: opennotificaties
+      DB_USER: opennotificaties
+      DB_PASSWORD: opennotificaties
+      IS_HTTPS: "no"
+      ALLOWED_HOSTS: "*"
+      CACHE_DEFAULT: nrc-redis:6379/0
+      CACHE_AXES: nrc-redis:6379/0
+      CELERY_BROKER_URL: redis://nrc-redis:6379/1
+      CELERY_RESULT_BACKEND: redis://nrc-redis:6379/1
+      DISABLE_2FA: "true"
+      OPENNOTIFICATIES_SUPERUSER_USERNAME: admin
+      DJANGO_SUPERUSER_PASSWORD: admin
+      OPENNOTIFICATIES_SUPERUSER_EMAIL: admin@localhost
+    command: ["sh", "-c", "/wait_for_db.sh && OTEL_SDK_DISABLED=True python src/manage.py migrate"]
+    depends_on:
+      nrc-db:
+        condition: service_healthy
+      nrc-redis:
+        condition: service_started
+      openzaak:
+        condition: service_healthy
+    networks: [cg]
+
+  nrc-web:
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-1.16.1}
+    environment: *nrc-env
+    healthcheck:
+      test: ["CMD", "python", "-c", "import requests,sys; sys.exit(0 if requests.head('http://localhost:8000/admin/').status_code in (200,302) else 1)"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+    ports:
+      - "8001:8000"
+    depends_on:
+      nrc-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+  nrc-celery:
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-1.16.1}
+    environment: *nrc-env
+    command: /celery_worker.sh
+    depends_on:
+      nrc-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+  # ── Keycloak (S-02) ──────────────────────────────────────────────────────
+  keycloak:
+    image: quay.io/keycloak/keycloak:26.1
+    command: ["start-dev", "--import-realm"]
+    environment:
+      KC_BOOTSTRAP_ADMIN_USERNAME: admin
+      KC_BOOTSTRAP_ADMIN_PASSWORD: admin
+      KEYCLOAK_ADMIN: admin
+      KEYCLOAK_ADMIN_PASSWORD: admin
+      KC_HEALTH_ENABLED: "true"
+      KC_HTTP_ENABLED: "true"
+    ports:
+      - "8180:8080"
+    volumes:
+      - ./keycloak/realms:/opt/keycloak/data/import:ro,z
+    networks: [cg]
+
+  # ── Flowable (S-03) ──────────────────────────────────────────────────────
+  flowable-db:
+    image: docker.io/library/postgres:16
+    environment:
+      POSTGRES_USER: flowable
+      POSTGRES_PASSWORD: flowable
+      POSTGRES_DB: flowable
+    volumes:
+      - flowable-db:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U flowable -d flowable"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    networks: [cg]
+
+  flowable-rest:
+    image: docker.io/flowable/flowable-rest:latest
+    environment:
+      SPRING_DATASOURCE_DRIVER-CLASS-NAME: org.postgresql.Driver
+      SPRING_DATASOURCE_URL: jdbc:postgresql://flowable-db:5432/flowable
+      SPRING_DATASOURCE_USERNAME: flowable
+      SPRING_DATASOURCE_PASSWORD: flowable
+    ports:
+      - "8090:8080"
+    depends_on:
+      flowable-db:
+        condition: service_healthy
+    networks: [cg]
+
+  flowable-init:
+    image: docker.io/curlimages/curl:latest
+    restart: "no"
+    volumes:
+      - ../workflows/registratie.bpmn:/work/registratie.bpmn:ro,z
+    command:
+      - sh
+      - -c
+      - |
+        base=http://flowable-rest:8080/flowable-rest/service/repository/deployments
+        until curl -sf -u rest-admin:test "$$base" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
+        if curl -s -u rest-admin:test "$$base?name=registratie" | grep -q '"name":"registratie"'; then
+          echo "registratie already deployed; skip"
+        else
+          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bpmn;filename=registratie.bpmn' "$$base" >/dev/null && echo "deployed registratie"
+        fi
+    depends_on:
+      flowable-rest:
+        condition: service_started
+    networks: [cg]
+
+  # ── ACL ──────────────────────────────────────────────────────────────────
+  acl:
+    build:
+      context: ../services/acl
+      dockerfile: Dockerfile
+    image: register-referentie/acl:dev
+    environment:
+      Acl__OpenZaak__BaseUrl: http://openzaak:8000/
+      Acl__OpenZaak__ClientId: big-reference-seed
+      Acl__OpenZaak__Secret: insecure-dev-secret-change-me
+      Acl__Defaults__Bronorganisatie: "517439943"
+      Acl__Defaults__VerantwoordelijkeOrganisatie: "517439943"
+      Acl__Defaults__Vertrouwelijkheidaanduiding: openbaar
+      Acl__Defaults__ZaaktypeUrl: ${ACL_ZAAKTYPE_URL:-http://openzaak:8000/catalogi/api/v1/zaaktypen/00000000-0000-0000-0000-000000000000}
+    ports:
+      - "8100:8080"
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+    depends_on:
+      openzaak:
+        condition: service_healthy
+    networks: [cg]
+
+  # ── BFF ──────────────────────────────────────────────────────────────────
+  bff:
+    build:
+      context: ../services/bff
+      dockerfile: Dockerfile
+    image: register-referentie/bff:dev
+    ports:
+      - "8080:8080"
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+    networks: [cg]
+
+volumes:
+  oz-db:
+  nrc-db:
+  flowable-db:
+
+networks:
+  cg:
@@ -1,9 +1,289 @@
-# Local development stack. Grows service-by-service with each slice.
-# S-00-b: the placeholder BFF with a /health check.
+# Development stack — boots all infra services plus the ACL and BFF.
+#
+# Consolidates infra/openzaak/, infra/opennotificaties/, infra/keycloak/,
+# and infra/flowable/ and adds the ACL and BFF services.
+#
+# Port map (host):
+#   8000  OpenZaak ZGW API  (admin: admin / admin)
+#   8001  Open Notificaties (admin: admin / admin)
+#   8080  BFF               GET /health → Healthy
+#   8090  Flowable REST     http://localhost:8090/flowable-rest/service/
+#   8100  ACL               GET /health → Healthy  POST /zaken
+#   8180  Keycloak          (admin: admin / admin)
 #
 #   docker compose -f infra/docker-compose.yml up -d --build --wait
-#   curl http://localhost:8080/health   # -> Healthy
+#
+# After first boot, seed the BIG catalogus and note the zaaktype URL:
+#   python infra/openzaak/seed_catalogus.py
+# Then set ACL_ZAAKTYPE_URL in a .env file or your shell and re-up the acl
+# service:
+#   export ACL_ZAAKTYPE_URL=http://openzaak:8000/catalogi/api/v1/zaaktypen/<uuid>
+#   docker compose -f infra/docker-compose.yml up -d acl
+
 services:
+
+  # ── OpenZaak (S-01) ──────────────────────────────────────────────────────
+  oz-db:
+    image: docker.io/postgis/postgis:17-3.5
+    environment:
+      POSTGRES_USER: openzaak
+      POSTGRES_PASSWORD: openzaak
+      POSTGRES_DB: openzaak
+    command: postgres -c max_connections=300
+    volumes:
+      - oz-db:/var/lib/postgresql/data
+    healthcheck:
+      # pg_isready only checks TCP; the second clause verifies PostGIS is installed
+      # so oz-init migrations can safely start (avoids race on cold container start).
+      test: ["CMD-SHELL", "pg_isready -U openzaak -d openzaak && psql -U openzaak -d openzaak -c 'SELECT PostGIS_Version();' -q 2>/dev/null"]
+      interval: 5s
+      timeout: 5s
+      retries: 30
+      start_period: 15s
+    networks: [cg]
+
+  oz-redis:
+    image: docker.io/library/redis:7
+    networks: [cg]
+
+  oz-init:
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-1.28.2}
+    environment: &oz-env
+      DJANGO_SETTINGS_MODULE: openzaak.conf.docker
+      SECRET_KEY: ${OZ_SECRET_KEY:-dev-only-not-for-production}
+      DB_HOST: oz-db
+      DB_NAME: openzaak
+      DB_USER: openzaak
+      DB_PASSWORD: openzaak
+      IS_HTTPS: "no"
+      ALLOWED_HOSTS: "*"
+      CACHE_DEFAULT: oz-redis:6379/0
+      CACHE_AXES: oz-redis:6379/0
+      CELERY_BROKER_URL: redis://oz-redis:6379/1
+      CELERY_RESULT_BACKEND: redis://oz-redis:6379/1
+      DISABLE_2FA: "true"
+      NOTIFICATIONS_DISABLED: "true"
+      OPENZAAK_SUPERUSER_USERNAME: admin
+      DJANGO_SUPERUSER_PASSWORD: admin
+      OPENZAAK_SUPERUSER_EMAIL: admin@localhost
+      RUN_SETUP_CONFIG: "true"
+    command: /setup_configuration.sh
+    # data.yaml is streamed into this external volume by infra/seed-config.sh
+    # before start (bind mounts don't reach sibling containers on the CI runner).
+    volumes:
+      - oz-config:/app/setup_configuration:ro
+    depends_on:
+      oz-db:
+        condition: service_healthy
+      oz-redis:
+        condition: service_started
+    networks: [cg]
+
+  openzaak:
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-1.28.2}
+    environment: *oz-env
+    healthcheck:
+      test: ["CMD", "python", "-c", "import requests,sys; sys.exit(0 if requests.head('http://localhost:8000/admin/').status_code in (200,302) else 1)"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+    ports:
+      - "8000:8000"
+    depends_on:
+      oz-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+  oz-celery:
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-1.28.2}
+    environment: *oz-env
+    command: /celery_worker.sh
+    depends_on:
+      oz-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+  # ── Open Notificaties / NRC (S-01-c) ─────────────────────────────────────
+  nrc-db:
+    image: docker.io/postgis/postgis:17-3.5
+    environment:
+      POSTGRES_USER: opennotificaties
+      POSTGRES_PASSWORD: opennotificaties
+      POSTGRES_DB: opennotificaties
+    command: postgres -c max_connections=300
+    volumes:
+      - nrc-db:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U opennotificaties -d opennotificaties"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    networks: [cg]
+
+  nrc-redis:
+    image: docker.io/library/redis:7
+    networks: [cg]
+
+  nrc-init:
+    # Plain base image — nrc-init runs migrations only (see command below), so it
+    # needs no baked config.
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-1.16.1}
+    environment: &nrc-env
+      DJANGO_SETTINGS_MODULE: nrc.conf.docker
+      SECRET_KEY: ${NRC_SECRET_KEY:-dev-only-not-for-production}
+      DB_HOST: nrc-db
+      DB_NAME: opennotificaties
+      DB_USER: opennotificaties
+      DB_PASSWORD: opennotificaties
+      IS_HTTPS: "no"
+      ALLOWED_HOSTS: "*"
+      CACHE_DEFAULT: nrc-redis:6379/0
+      CACHE_AXES: nrc-redis:6379/0
+      CELERY_BROKER_URL: redis://nrc-redis:6379/1
+      CELERY_RESULT_BACKEND: redis://nrc-redis:6379/1
+      DISABLE_2FA: "true"
+      OPENNOTIFICATIES_SUPERUSER_USERNAME: admin
+      DJANGO_SUPERUSER_PASSWORD: admin
+      OPENNOTIFICATIES_SUPERUSER_EMAIL: admin@localhost
+    # Migrations only for now. No setup_configuration steps are enabled yet (the
+    # OZ<->NRC notification wiring lands in S-06), and NRC's `setup_configuration`
+    # aborts with "No steps enabled" on the empty data.yaml — so we run `migrate`
+    # directly instead of /setup_configuration.sh. See data.yaml and ADR-0002.
+    command: ["sh", "-c", "/wait_for_db.sh && OTEL_SDK_DISABLED=True python src/manage.py migrate"]
+    depends_on:
+      nrc-db:
+        condition: service_healthy
+      nrc-redis:
+        condition: service_started
+      openzaak:
+        condition: service_healthy
+    networks: [cg]
+
+  nrc-web:
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-1.16.1}
+    environment: *nrc-env
+    healthcheck:
+      test: ["CMD", "python", "-c", "import requests,sys; sys.exit(0 if requests.head('http://localhost:8000/admin/').status_code in (200,302) else 1)"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+    ports:
+      - "8001:8000"
+    depends_on:
+      nrc-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+  nrc-celery:
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-1.16.1}
+    environment: *nrc-env
+    command: /celery_worker.sh
+    depends_on:
+      nrc-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+  # ── Keycloak (S-02) ──────────────────────────────────────────────────────
+  keycloak:
+    image: quay.io/keycloak/keycloak:26.1
+    command: ["start-dev", "--import-realm"]
+    environment:
+      KC_BOOTSTRAP_ADMIN_USERNAME: admin
+      KC_BOOTSTRAP_ADMIN_PASSWORD: admin
+      KEYCLOAK_ADMIN: admin
+      KEYCLOAK_ADMIN_PASSWORD: admin
+      KC_HEALTH_ENABLED: "true"
+      KC_HTTP_ENABLED: "true"
+    ports:
+      - "8180:8080"
+    # realm exports are streamed into this external volume by infra/seed-config.sh.
+    volumes:
+      - kc-realms:/opt/keycloak/data/import:ro
+    networks: [cg]
+
+  # ── Flowable (S-03) ──────────────────────────────────────────────────────
+  flowable-db:
+    image: docker.io/library/postgres:16
+    environment:
+      POSTGRES_USER: flowable
+      POSTGRES_PASSWORD: flowable
+      POSTGRES_DB: flowable
+    volumes:
+      - flowable-db:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U flowable -d flowable"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    networks: [cg]
+
+  flowable-rest:
+    image: docker.io/flowable/flowable-rest:latest
+    environment:
+      SPRING_DATASOURCE_DRIVER-CLASS-NAME: org.postgresql.Driver
+      SPRING_DATASOURCE_URL: jdbc:postgresql://flowable-db:5432/flowable
+      SPRING_DATASOURCE_USERNAME: flowable
+      SPRING_DATASOURCE_PASSWORD: flowable
+    ports:
+      - "8090:8080"
+    depends_on:
+      flowable-db:
+        condition: service_healthy
+    networks: [cg]
+
+  flowable-init:
+    image: docker.io/curlimages/curl:latest
+    restart: "no"
+    # registratie.bpmn is 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
+        until curl -sf -u rest-admin:test "$$base" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
+        if curl -s -u rest-admin:test "$$base?name=registratie" | grep -q '"name":"registratie"'; then
+          echo "registratie already deployed; skip"
+        else
+          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bpmn;filename=registratie.bpmn' "$$base" >/dev/null && echo "deployed registratie"
+        fi
+    depends_on:
+      flowable-rest:
+        condition: service_started
+    networks: [cg]
+
+  # ── ACL ──────────────────────────────────────────────────────────────────
+  acl:
+    build:
+      context: ../services/acl
+      dockerfile: Dockerfile
+    image: register-referentie/acl:dev
+    environment:
+      Acl__OpenZaak__BaseUrl: http://openzaak:8000/
+      Acl__OpenZaak__ClientId: big-reference-seed
+      Acl__OpenZaak__Secret: insecure-dev-secret-change-me
+      Acl__Defaults__Bronorganisatie: "517439943"
+      Acl__Defaults__VerantwoordelijkeOrganisatie: "517439943"
+      Acl__Defaults__Vertrouwelijkheidaanduiding: openbaar
+      # Override with the real zaaktype URL after running seed_catalogus.py.
+      Acl__Defaults__ZaaktypeUrl: ${ACL_ZAAKTYPE_URL:-http://openzaak:8000/catalogi/api/v1/zaaktypen/00000000-0000-0000-0000-000000000000}
+    ports:
+      - "8100:8080"
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+    depends_on:
+      openzaak:
+        condition: service_healthy
+    networks: [cg]
+
+  # ── BFF ──────────────────────────────────────────────────────────────────
  bff:
    build:
      context: ../services/bff
@@ -17,3 +297,24 @@ services:
      timeout: 3s
      retries: 5
      start_period: 10s
+    networks: [cg]
+
+volumes:
+  oz-db:
+  nrc-db:
+  flowable-db:
+  # Config volumes — created and populated out-of-band by infra/seed-config.sh
+  # (docker cp), because bind mounts don't reach sibling containers on the CI
+  # runner. `external` keeps the names deterministic; the seed step manages them.
+  oz-config:
+    external: true
+    name: rr-oz-config
+  kc-realms:
+    external: true
+    name: rr-kc-realms
+  fl-bpmn:
+    external: true
+    name: rr-fl-bpmn
+
+networks:
+  cg:
@@ -40,8 +40,9 @@ services:
  flowable-init:
    image: docker.io/curlimages/curl:latest
    restart: "no"
+    # registratie.bpmn is streamed into this external volume by infra/seed-config.sh.
    volumes:
-      - ../../workflows/registratie.bpmn:/work/registratie.bpmn:ro,z
+      - fl-bpmn:/work:ro
    command:
      - sh
      - -c
@@ -60,6 +61,10 @@ services:

 volumes:
  flowable-db:
+  # populated out-of-band by infra/seed-config.sh (docker cp) — see that script.
+  fl-bpmn:
+    external: true
+    name: rr-fl-bpmn

 networks:
  cg:
@@ -21,9 +21,15 @@ services:
      KC_HTTP_ENABLED: "true"
    ports:
      - "8180:8080"
+    # realm exports are streamed into this external volume by infra/seed-config.sh.
    volumes:
-      - ./realms:/opt/keycloak/data/import:ro,z
+      - kc-realms:/opt/keycloak/data/import:ro
    networks: [cg]

+volumes:
+  kc-realms:
+    external: true
+    name: rr-kc-realms
+
 networks:
  cg:
@@ -19,10 +19,13 @@ services:
    volumes:
      - nrc-db:/var/lib/postgresql/data
    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U opennotificaties -d opennotificaties"]
+      # pg_isready only checks TCP; the second clause verifies PostGIS is installed
+      # so nrc-init migrations can safely start (avoids race on cold container start).
+      test: ["CMD-SHELL", "pg_isready -U opennotificaties -d opennotificaties && psql -U opennotificaties -d opennotificaties -c 'SELECT PostGIS_Version();' -q 2>/dev/null"]
      interval: 5s
-      timeout: 3s
-      retries: 10
+      timeout: 5s
+      retries: 30
+      start_period: 15s
    networks: [cg]

  nrc-redis:
@@ -30,7 +33,8 @@ services:
    networks: [cg]

  nrc-init:
-    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-latest}
+    # Plain base image — nrc-init runs migrations only (see command below).
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-1.16.1}
    environment: &nrc-env
      DJANGO_SETTINGS_MODULE: nrc.conf.docker
      SECRET_KEY: ${NRC_SECRET_KEY:-dev-only-not-for-production}
@@ -48,10 +52,11 @@ services:
      OPENNOTIFICATIES_SUPERUSER_USERNAME: admin
      DJANGO_SUPERUSER_PASSWORD: admin
      OPENNOTIFICATIES_SUPERUSER_EMAIL: admin@localhost
-      RUN_SETUP_CONFIG: "true"
-    command: /setup_configuration.sh
-    volumes:
-      - ./setup_configuration:/app/setup_configuration:ro,z
+    # Migrations only for now. No setup_configuration steps are enabled yet (the
+    # OZ<->NRC notification wiring lands in S-06), and NRC's `setup_configuration`
+    # aborts with "No steps enabled" on the empty data.yaml — so we run `migrate`
+    # directly instead of /setup_configuration.sh. See data.yaml and ADR-0002.
+    command: ["sh", "-c", "/wait_for_db.sh && OTEL_SDK_DISABLED=True python src/manage.py migrate"]
    depends_on:
      nrc-db:
        condition: service_healthy
@@ -60,7 +65,7 @@ services:
    networks: [cg]

  nrc-web:
-    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-latest}
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-1.16.1}
    environment: *nrc-env
    healthcheck:
      test: ["CMD", "python", "-c", "import requests,sys; sys.exit(0 if requests.head('http://localhost:8000/admin/').status_code in (200,302) else 1)"]
@@ -76,7 +81,7 @@ services:
    networks: [cg]

  nrc-celery:
-    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-latest}
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-1.16.1}
    environment: *nrc-env
    command: /celery_worker.sh
    depends_on:
@@ -18,10 +18,13 @@ services:
    volumes:
      - oz-db:/var/lib/postgresql/data
    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U openzaak -d openzaak"]
+      # pg_isready only checks TCP; the second clause verifies PostGIS is installed
+      # so oz-init migrations can safely start (avoids race on cold container start).
+      test: ["CMD-SHELL", "pg_isready -U openzaak -d openzaak && psql -U openzaak -d openzaak -c 'SELECT PostGIS_Version();' -q 2>/dev/null"]
      interval: 5s
-      timeout: 3s
-      retries: 10
+      timeout: 5s
+      retries: 30
+      start_period: 15s
    networks: [cg]

  oz-redis:
@@ -29,7 +32,7 @@ services:
    networks: [cg]

  oz-init:
-    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-latest}
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-1.28.2}
    environment: &oz-env
      DJANGO_SETTINGS_MODULE: openzaak.conf.docker
      SECRET_KEY: ${OZ_SECRET_KEY:-dev-only-not-for-production}
@@ -52,10 +55,9 @@ services:
      OPENZAAK_SUPERUSER_EMAIL: admin@localhost
      RUN_SETUP_CONFIG: "true"
    command: /setup_configuration.sh
+    # data.yaml is streamed into this external volume by infra/seed-config.sh.
    volumes:
-      # :z relabels for SELinux; the dir/file must be world-readable for the
-      # container user (rootless Podman uid mapping). See docs/runbooks/openzaak.md.
-      - ./setup_configuration:/app/setup_configuration:ro,z
+      - oz-config:/app/setup_configuration:ro
    depends_on:
      oz-db:
        condition: service_healthy
@@ -64,7 +66,7 @@ services:
    networks: [cg]

  openzaak:
-    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-latest}
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-1.28.2}
    environment: *oz-env
    healthcheck:
      test: ["CMD", "python", "-c", "import requests,sys; sys.exit(0 if requests.head('http://localhost:8000/admin/').status_code in (200,302) else 1)"]
@@ -80,7 +82,7 @@ services:
    networks: [cg]

  oz-celery:
-    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-latest}
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-1.28.2}
    environment: *oz-env
    command: /celery_worker.sh
    depends_on:
@@ -90,6 +92,10 @@ services:

 volumes:
  oz-db:
+  # populated out-of-band by infra/seed-config.sh (docker cp) — see that script.
+  oz-config:
+    external: true
+    name: rr-oz-config

 networks:
  cg:
@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+#
+# Populate the external named *config* volumes that the upstream services mount,
+# by `docker cp`-ing files into a throwaway helper container that mounts each one.
+#
+# Why: the compose stack uses the upstream images verbatim (no build). On Gitea's
+# containerized runner, `docker compose` starts the stack as SIBLING containers
+# via the host daemon, so a workspace bind mount resolves to a path the daemon
+# can't see and is mounted empty. `docker cp` instead streams bytes over the
+# Docker API, so the files reach the volume regardless of where the daemon runs.
+# We use plain docker primitives (volume create / run / cp / rm) rather than
+# `docker compose create`, because podman-compose (local dev) lacks that
+# subcommand. Fixed-name `external` volumes keep the names deterministic across
+# both runtimes. See docs/runbooks/gitea-actions-gotchas.md.
+#
+# Usage: seed-config.sh <key> [<key> ...]   where key ∈ { oz, kc, fl }
+set -euo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HELPER="${SEED_HELPER_IMAGE:-docker.io/library/busybox:stable}"
+
+populate() {  # volume  source(file or dir/.)
+  local vol="$1" src="$2" cid
+  docker volume rm -f "$vol" >/dev/null 2>&1 || true
+  docker volume create "$vol" >/dev/null
+  # A *created* (never started) helper is enough: the volume is attached at create
+  # time, `docker cp` writes through to it, and `docker rm` is instant (nothing to
+  # stop). `docker create` is a container subcommand both docker and podman have —
+  # unlike `docker compose create`, which podman-compose lacks.
+  cid="$(docker create -v "$vol:/dest" "$HELPER" true)"
+  docker cp "$src" "$cid:/dest/"
+  docker rm "$cid" >/dev/null
+  echo "  seeded $vol"
+}
+
+[ "$#" -gt 0 ] || { echo "usage: seed-config.sh <oz|kc|fl> ..." >&2; exit 2; }
+
+for key in "$@"; do
+  case "$key" in
+    oz) populate rr-oz-config "$here/openzaak/setup_configuration/." ;;
+    kc) populate rr-kc-realms "$here/keycloak/realms/." ;;
+    fl) populate rr-fl-bpmn  "$here/../workflows/registratie.bpmn" ;;
+    *)  echo "unknown seed key: $key" >&2; exit 2 ;;
+  esac
+done
@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+#
+# Wait until the named compose services report a healthy healthcheck.
+#
+# Portable across `docker compose` (CI) and `podman-compose` (local dev): it uses
+# plain `docker ps` + `docker inspect`, so it needs neither `docker compose
+# up --wait` (podman-compose doesn't implement that flag) nor host port access
+# (the containerized CI runner can't reach published ports). It also sidesteps the
+# `--wait`-fails-when-a-one-shot-exits issue, since we only poll long-running
+# services that declare a healthcheck. See docs/runbooks/gitea-actions-gotchas.md.
+#
+# Usage: WAIT_TIMEOUT=420 wait-healthy.sh <service> [<service> ...]
+set -euo pipefail
+
+timeout="${WAIT_TIMEOUT:-420}"
+deadline=$(( $(date +%s) + timeout ))
+
+# compose service name -> container id. The name filter matches both docker
+# compose ("infra-openzaak-1") and podman-compose ("infra_openzaak_1") naming.
+cid_for() { docker ps -aq --filter "name=$1" | head -1; }
+
+for svc in "$@"; do
+  echo "waiting for '$svc' to be healthy (timeout ${timeout}s)..."
+  while :; do
+    cid="$(cid_for "$svc")"
+    status=""
+    [ -n "$cid" ] && status="$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}' "$cid" 2>/dev/null || true)"
+    [ "$status" = "healthy" ] && { echo "  '$svc' is healthy"; break; }
+    if [ "$(date +%s)" -ge "$deadline" ]; then
+      echo "TIMEOUT: '$svc' not healthy (status=${status:-no-container})" >&2
+      docker ps -a --filter "name=$svc" >&2 || true
+      exit 1
+    fi
+    sleep 3
+  done
+done
@@ -26,17 +26,7 @@ nav:
      - "ADR-0002: Catalogus design": architecture/adr-0002-catalogus-design.md
      - "ADR-0003: ACL default-fill": architecture/adr-0003-default-fill.md
      - "ADR-0004: BDD framework": architecture/adr-0004-bdd-framework.md
-  - FDS-architectuur:
-      - Overzicht: architecture/fds/README.md
-      - Componentview (L3): architecture/fds/c4-component-view.md
-      - "Slice 1: walking skeleton": architecture/fds/slice-1-proposal.md
-      - "ADR-0001: ACL op elke registergrens": architecture/fds/adr/0001-acl-at-every-register-boundary.md
-      - "ADR-0002: FSC voor connectiviteit": architecture/fds/adr/0002-fsc-for-connectivity.md
-      - "ADR-0003: PBAC via OPA": architecture/fds/adr/0003-pbac-via-opa.md
-      - "ADR-0004: Begrensde cache": architecture/fds/adr/0004-bounded-cache.md
-      - "ADR-0005: Verwerkingenlog via events": architecture/fds/adr/0005-ldv-verwerkingenlog.md
-      - "ADR-0006: Modulegrens en hergebruik": architecture/fds/adr/0006-module-boundary-and-reuse.md
-      - "ADR-template (FDS)": architecture/fds/adr/template.md
+      - "ADR-0005: Mutation testing": architecture/adr-0005-mutation-testing.md
  - Working in Gitea: gitea-workflow.md
  - Runbooks:
      - CI: runbooks/ci.md
@@ -45,11 +35,7 @@ markdown_extensions:
  - admonition
  - toc:
      permalink: true
-  - pymdownx.superfences:
-      custom_fences:
-        - name: mermaid
-          class: mermaid
-          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.superfences

 # Many docs referenced by PRD.md land in later slices; don't fail the build on them.
 validation:
@@ -0,0 +1,3 @@
+**/bin
+**/obj
+**/*.user
@@ -44,4 +44,21 @@ public class AclServiceTests
        Assert.Equal(defaults.ZaaktypeUrl, req.Zaaktype);
        Assert.Equal(new DateOnly(2026, 6, 4), req.Startdatum);
    }
+
+    [Fact]
+    public async Task Rejects_a_null_registration_without_calling_the_gateway()
+    {
+        var gateway = new FakeGateway();
+        var defaults = new AclDefaults
+        {
+            Bronorganisatie = "517439943",
+            VerantwoordelijkeOrganisatie = "517439943",
+            Vertrouwelijkheidaanduiding = "openbaar",
+            ZaaktypeUrl = new("http://openzaak/catalogi/api/v1/zaaktypen/big"),
+        };
+        var service = new AclService(gateway, defaults, new FixedClock(new DateOnly(2026, 6, 4)));
+
+        await Assert.ThrowsAsync<ArgumentNullException>(() => service.OpenZaakAsync(null!));
+        Assert.Null(gateway.Captured);
+    }
 }
@@ -1,5 +1,7 @@
 using System.Net;
 using System.Net.Http.Json;
+using System.Text;
+using System.Text.Json;
 using Acl.Application;
 using Acl.Infrastructure;

@@ -14,38 +16,120 @@ public class OpenZaakGatewayTests
            => onSend(request);
    }

-    [Fact]
-    public async Task Posts_zaak_to_openzaak_with_bearer_and_default_fields_and_returns_url()
+    private static OpenZaakGateway Gateway(StubHandler handler) => new(
+        new HttpClient(handler),
+        new OpenZaakOptions { BaseUrl = new("http://openzaak"), ClientId = "cid", Secret = "sec" });
+
+    private static ZaakRequest SampleRequest() => new(
+        "517439943", "517439943", "openbaar",
+        new("http://openzaak/catalogi/api/v1/zaaktypen/big"), new DateOnly(2026, 6, 4));
+
+    private static StubHandler Created(out RequestCapture capture)
    {
-        HttpRequestMessage? seen = null;
-        string? body = null;
-        var handler = new StubHandler(async req =>
+        var c = new RequestCapture();
+        capture = c;
+        return new StubHandler(async req =>
        {
-            seen = req;
-            body = await req.Content!.ReadAsStringAsync();
+            c.Seen = req;
+            c.Body = req.Content is null ? null : await req.Content.ReadAsStringAsync();
            return new HttpResponseMessage(HttpStatusCode.Created)
            {
                Content = JsonContent.Create(new { url = "http://openzaak/zaken/api/v1/zaken/xyz" }),
            };
        });
-        var gateway = new OpenZaakGateway(
-            new HttpClient(handler),
-            new OpenZaakOptions { BaseUrl = new("http://openzaak"), ClientId = "cid", Secret = "sec" });
-        var request = new ZaakRequest(
-            "517439943", "517439943", "openbaar",
-            new("http://openzaak/catalogi/api/v1/zaaktypen/big"), new DateOnly(2026, 6, 4));
+    }

-        var url = await gateway.OpenZaakAsync(request);
+    private sealed class RequestCapture
+    {
+        public HttpRequestMessage? Seen;
+        public string? Body;
+    }
+
+    [Fact]
+    public async Task Posts_zaak_to_openzaak_with_bearer_and_default_fields_and_returns_url()
+    {
+        var handler = Created(out var capture);
+
+        var url = await Gateway(handler).OpenZaakAsync(SampleRequest());

        Assert.Equal("http://openzaak/zaken/api/v1/zaken/xyz", url.ToString());
-        Assert.Equal(HttpMethod.Post, seen!.Method);
-        Assert.Equal("http://openzaak/zaken/api/v1/zaken", seen.RequestUri!.ToString());
-        Assert.Equal("Bearer", seen.Headers.Authorization!.Scheme);
-        Assert.False(string.IsNullOrWhiteSpace(seen.Headers.Authorization.Parameter));
-        Assert.Contains("\"bronorganisatie\":\"517439943\"", body);
-        Assert.Contains("\"verantwoordelijkeOrganisatie\":\"517439943\"", body);
-        Assert.Contains("\"vertrouwelijkheidaanduiding\":\"openbaar\"", body);
-        Assert.Contains("\"startdatum\":\"2026-06-04\"", body);
-        Assert.Contains("\"zaaktype\":\"http://openzaak/catalogi/api/v1/zaaktypen/big\"", body);
+        Assert.Equal(HttpMethod.Post, capture.Seen!.Method);
+        Assert.Equal("http://openzaak/zaken/api/v1/zaken", capture.Seen.RequestUri!.ToString());
+        Assert.Equal("Bearer", capture.Seen.Headers.Authorization!.Scheme);
+        Assert.False(string.IsNullOrWhiteSpace(capture.Seen.Headers.Authorization.Parameter));
+        Assert.Contains("\"bronorganisatie\":\"517439943\"", capture.Body);
+        Assert.Contains("\"verantwoordelijkeOrganisatie\":\"517439943\"", capture.Body);
+        Assert.Contains("\"vertrouwelijkheidaanduiding\":\"openbaar\"", capture.Body);
+        Assert.Contains("\"startdatum\":\"2026-06-04\"", capture.Body);
+        Assert.Contains("\"zaaktype\":\"http://openzaak/catalogi/api/v1/zaaktypen/big\"", capture.Body);
+    }
+
+    [Fact]
+    public async Task Sends_the_geo_crs_headers_required_by_the_zaken_api()
+    {
+        var handler = Created(out var capture);
+
+        await Gateway(handler).OpenZaakAsync(SampleRequest());
+
+        Assert.Equal("EPSG:4326", Assert.Single(capture.Seen!.Headers.GetValues("Accept-Crs")));
+        Assert.Equal("EPSG:4326", Assert.Single(capture.Seen.Content!.Headers.GetValues("Content-Crs")));
+    }
+
+    [Fact]
+    public async Task Mints_a_hs256_jwt_carrying_the_acl_identity_claims()
+    {
+        var handler = Created(out var capture);
+
+        await Gateway(handler).OpenZaakAsync(SampleRequest());
+
+        var parts = capture.Seen!.Headers.Authorization!.Parameter!.Split('.');
+        Assert.Equal(3, parts.Length);
+        using var header = JsonDocument.Parse(DecodeSegment(parts[0]));
+        Assert.Equal("HS256", header.RootElement.GetProperty("alg").GetString());
+        Assert.Equal("JWT", header.RootElement.GetProperty("typ").GetString());
+        using var payload = JsonDocument.Parse(DecodeSegment(parts[1]));
+        Assert.Equal("cid", payload.RootElement.GetProperty("client_id").GetString());
+        Assert.Equal("acl", payload.RootElement.GetProperty("user_id").GetString());
+        Assert.Equal("acl", payload.RootElement.GetProperty("user_representation").GetString());
+    }
+
+    [Fact]
+    public async Task Throws_when_openzaak_rejects_the_request()
+    {
+        var handler = new StubHandler(_ =>
+            Task.FromResult(new HttpResponseMessage(HttpStatusCode.BadRequest)));
+
+        await Assert.ThrowsAsync<HttpRequestException>(
+            () => Gateway(handler).OpenZaakAsync(SampleRequest()));
+    }
+
+    [Fact]
+    public async Task Throws_when_openzaak_returns_an_empty_body()
+    {
+        var handler = new StubHandler(_ =>
+            Task.FromResult(new HttpResponseMessage(HttpStatusCode.Created)
+            {
+                Content = new StringContent("null", Encoding.UTF8, "application/json"),
+            }));
+
+        await Assert.ThrowsAsync<InvalidOperationException>(
+            () => Gateway(handler).OpenZaakAsync(SampleRequest()));
+    }
+
+    [Fact]
+    public async Task Rejects_a_null_request()
+    {
+        var handler = new StubHandler(_ => throw new InvalidOperationException("should not be sent"));
+
+        await Assert.ThrowsAsync<ArgumentNullException>(
+            () => Gateway(handler).OpenZaakAsync(null!));
+    }
+
+    // ZGW tokens are base64url with padding stripped (ZgwToken.B64Url); restore it to decode.
+    private static string DecodeSegment(string segment)
+    {
+        var b64 = segment.Replace('-', '+').Replace('_', '/');
+        b64 = (b64.Length % 4) switch { 2 => b64 + "==", 3 => b64 + "=", _ => b64 };
+        return Encoding.UTF8.GetString(Convert.FromBase64String(b64));
    }
 }
@@ -0,0 +1,32 @@
+# Multi-stage build for the ACL service (.NET 10).
+# Build context is services/acl (see infra/docker-compose.yml).
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+
+# Restore first (cached unless .csproj files change).
+COPY Acl.Api/Acl.Api.csproj Acl.Api/
+COPY Acl.Application/Acl.Application.csproj Acl.Application/
+COPY Acl.Infrastructure/Acl.Infrastructure.csproj Acl.Infrastructure/
+RUN dotnet restore Acl.Api/Acl.Api.csproj
+
+COPY Acl.Api/ Acl.Api/
+COPY Acl.Application/ Acl.Application/
+COPY Acl.Infrastructure/ Acl.Infrastructure/
+RUN dotnet publish Acl.Api/Acl.Api.csproj -c Release -o /app/publish /p:UseAppHost=false
+
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime
+WORKDIR /app
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=build /app/publish .
+
+ENV ASPNETCORE_URLS=http://+:8080
+EXPOSE 8080
+
+HEALTHCHECK --interval=5s --timeout=3s --start-period=10s --retries=5 \
+    CMD curl -fsS http://localhost:8080/health || exit 1
+
+ENTRYPOINT ["dotnet", "Acl.Api.dll"]
@@ -0,0 +1,11 @@
+{
+  "stryker-config": {
+    "solution": "Acl.slnx",
+    "reporters": ["progress", "html"],
+    "thresholds": {
+      "high": 95,
+      "low": 90,
+      "break": 90
+    }
+  }
+}