feat(acl): resolve the zaaktype by identificatie, not a pinned URL (S-27, closes #113) (#118)

## What & why

The ACL was handed a **pinned zaaktype URL** (`Acl__Defaults__ZaaktypeUrl`) + informatieobjecttype URL. OpenZaak assigns those UUIDs at creation, so every stack had to seed the catalogus and then capture + inject the resulting URLs out of band (CI's `run-domain-check.sh`; the local `local-seed`→`acl.env` bootstrap from ADR-0020). Brittle, and a stale/placeholder URL failed opaquely (OpenZaak 400).

Now **the ACL resolves them itself** from OpenZaak's Catalogi API by stable business key:
- config `ZaaktypeIdentificatie` (`BIG-REGISTRATIE`) / `InformatieobjecttypeOmschrijving` (`Diploma`);
- a `CachedZaaktypeCatalog` resolves **lazily on first use** and caches (success only, so a pre-publish miss is retried — no startup ordering coupling);
- a clear "No published … found" error replaces the opaque placeholder 400.

Design in **ADR-0021** (proposed in #117).

Closes #113
Closes #117

## Consequences (the payoff)

No stack captures/injects a server-assigned URL any more — `docker-compose.yml`/`.local.yml`, `run-domain-check.sh` and `local-seed` all drop it; the local `acl.env` shrinks to a single line.

**One thing S-27 can't remove** (confirmed empirically during this work): OpenZaak validates the `zaaktype` field on zaak-create with Django's URLValidator and **rejects a single-label host** (`http://openzaak:8000/…` → `zaaktype: bad-url`). So the ACL's **base URL** must still point at a URL-valid host (a container IP); that base-URL injection from ADR-0020 stays (local `acl.env` now carries only it; CI keeps `ACL_OPENZAAK_BASEURL`). ADR-0021 records this.

## Definition of Done

- [x] Linked issues (#113 slice, #117 adr-proposal).
- [x] TDD — resolver + gateway-lookup unit tests, updated `AclService` tests (50 unit tests green).
- [x] Implementation makes them pass; refactor of both compose stacks + verify scripts follows.
- [x] Conventional Commits referencing #113.
- [ ] CI green — see below.
- [x] `docker compose up` reaches green health — verified: fresh `make local` + `make verify-local` green with **no zaaktype-URL injection**; `acl.env` is base-URL-only.
- [x] Docs — ADR-0021 + demo-script S-27 note.
- [x] ADR added (ADR-0021).
- [x] Demo note appended.

## Verification done locally

- **50 unit tests** pass (resolver resolve/cache/retry-on-failure; gateway match/miss/blank-key; all `AclService` paths).
- **6 ACL integration tests** pass against a live seeded OpenZaak — incl. resolving the zaaktype + Diploma iot by business key, and a clear error for an unknown identificatie.
- **Fresh `make local` + `make verify-local`**: full flow (submit → werkbak → openbaar) green; `acl.env` = `Acl__OpenZaak__BaseUrl` only.
- `make lint` clean; ACL mutation ratchet run locally (see checks).

## Notes for reviewers

- `IZaakGateway` gains two resolve methods; `AclService` depends on the new `IZaaktypeCatalog` (singleton, so the cache persists).
- Supersedes the pinned-URL mechanism; ADR-0021 documents that ADR-0020's `seed-env`/entrypoint shim are **simplified** (base-URL only), not deleted, because of the URLValidator constraint above.

Reviewed-on: #118

infra/docker-compose.local.yml

@@ -315,21 +315,22 @@ services:
       context: ../services/acl
       dockerfile: Dockerfile
     image: register-referentie/acl:dev
-    # The base/zaaktype/informatieobjecttype below are PLACEHOLDERS. The real, server-assigned
-    # values are written by the local-seed one-shot into seed-env:/seed/acl.env, which the entrypoint
-    # sources (set -a) so they override these before the app starts (S-B04, #110, ADR-0020). Sourcing
-    # a runtime-generated env file is why we override the entrypoint here rather than use `env_file:`
-    # (which compose reads at parse time, before the seed has run).
+    # The ACL discovers its zaaktype + informatieobjecttype URLs from the Catalogi API by the business
+    # keys below (S-27, ADR-0021), so no URL is injected. It still needs its OpenZaak BaseUrl pointed at
+    # a URL-valid host (OpenZaak rejects a single-label host like `openzaak` on zaak-create), so the
+    # local-seed one-shot writes that IP base into seed-env:/seed/acl.env, which the entrypoint sources
+    # (set -a) before the app starts. A runtime-generated env file is why we override the entrypoint here
+    # rather than use `env_file:` (which compose reads at parse time, before the seed has run).
     entrypoint: ["/bin/sh", "-c", "set -a; . /seed/acl.env; set +a; exec dotnet Acl.Api.dll"]
     environment:
-      Acl__OpenZaak__BaseUrl: http://openzaak:8000/
+      Acl__OpenZaak__BaseUrl: http://openzaak:8000/   # placeholder; seed-env/acl.env supplies the IP base
       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: http://openzaak:8000/catalogi/api/v1/zaaktypen/00000000-0000-0000-0000-000000000000
-      Acl__Defaults__InformatieobjecttypeUrl: http://openzaak:8000/catalogi/api/v1/informatieobjecttypen/00000000-0000-0000-0000-000000000000
+      Acl__Defaults__ZaaktypeIdentificatie: BIG-REGISTRATIE
+      Acl__Defaults__InformatieobjecttypeOmschrijving: Diploma
     ports:
       - "8100:8080"
     volumes:

infra/docker-compose.yml

@@ -15,12 +15,12 @@
 #
 #   docker compose -f infra/docker-compose.yml up -d --build --wait
 #
-# 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
+# After first boot, seed + publish the BIG catalogus:
+#   OZ_PUBLISH=1 python infra/openzaak/seed_catalogus.py
+# The ACL discovers the zaaktype by identificatie (S-27, ADR-0021), so there is no URL to inject —
+# just point its BaseUrl at an OpenZaak host OpenZaak accepts on zaak-create (a container IP; a
+# single-label host is rejected):
+#   ACL_OPENZAAK_BASEURL=http://<openzaak-ip>:8000/ docker compose -f infra/docker-compose.yml up -d acl
 
 services:
 
@@ -304,11 +304,12 @@ services:
       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}
-      # The informatieobjecttype a diploma is filed under (S-10b). Placeholder until seed_catalogus.py
-      # (OZ_PUBLISH=1) reports the real URL, which verify-domain injects like the zaaktype URL.
-      Acl__Defaults__InformatieobjecttypeUrl: ${ACL_INFORMATIEOBJECTTYPE_URL:-http://openzaak:8000/catalogi/api/v1/informatieobjecttypen/00000000-0000-0000-0000-000000000000}
+      # The ACL resolves the (server-assigned) zaaktype + diploma informatieobjecttype URLs from the
+      # Catalogi API by these stable business keys (S-27, ADR-0021) — no URL to capture and inject.
+      # BaseUrl above stays overridable because OpenZaak rejects a single-label host on zaak creation,
+      # so verify-domain still points the ACL at OpenZaak's container IP.
+      Acl__Defaults__ZaaktypeIdentificatie: BIG-REGISTRATIE
+      Acl__Defaults__InformatieobjecttypeOmschrijving: Diploma
     ports:
       - "8100:8080"
     healthcheck:

infra/local/seed-zaaktype.sh

@@ -21,15 +21,13 @@ echo ">> seeding + publishing the BIG zaaktype at ${OZ_BASE} (idempotent)"
 out="$(python3 /work/seed_catalogus.py)"
 echo "$out"
 
-zt="$(printf '%s\n' "$out" | sed -n 's/^ZAAKTYPE_URL //p' | head -1)"
-iot="$(printf '%s\n' "$out" | sed -n 's/^INFORMATIEOBJECTTYPE_URL //p' | head -1)"
-[ -n "$zt" ] || { echo "ERROR: seed did not report a ZAAKTYPE_URL" >&2; exit 1; }
-[ -n "$iot" ] || { echo "ERROR: seed did not report an INFORMATIEOBJECTTYPE_URL" >&2; exit 1; }
+# Sanity-check that the zaaktype was actually published (the ACL discovers it by identificatie, S-27).
+printf '%s\n' "$out" | grep -q '^ZAAKTYPE_URL ' || { echo "ERROR: seed did not publish the zaaktype" >&2; exit 1; }
 
-# The ACL entrypoint sources this; these keys override the placeholder defaults in the compose file.
+# The ACL resolves the zaaktype/informatieobjecttype URLs itself (S-27, ADR-0021); the only value it
+# still needs injected is the OpenZaak base URL at a URL-valid host (the container IP), because OpenZaak
+# rejects a single-label host on zaak-create. The ACL entrypoint sources this.
 cat > /out/acl.env <<EOF
 Acl__OpenZaak__BaseUrl=${OZ_BASE}/
-Acl__Defaults__ZaaktypeUrl=${zt}
-Acl__Defaults__InformatieobjecttypeUrl=${iot}
 EOF
-echo ">> wrote /out/acl.env (base=${OZ_BASE}/ zaaktype=${zt})"
+echo ">> wrote /out/acl.env (base=${OZ_BASE}/)"

infra/run-domain-check.sh

@@ -30,21 +30,18 @@ oz_ip="$(ip "$oz")"; dom_ip="$(ip "$dom")"
 oz_base="http://$oz_ip:8000"
 echo ">> openzaak=$oz_ip domain=$dom_ip network=$net"
 
-echo ">> seeding a published BIG zaaktype (idempotent) and capturing its URL"
+echo ">> seeding + publishing a BIG zaaktype (idempotent)"
 sid="$(docker create --network "$net" -e "OZ_BASE=$oz_base" -e OZ_PUBLISH=1 python:3-slim python /seed.py)"
 docker cp "$here/openzaak/seed_catalogus.py" "$sid:/seed.py" >/dev/null
 seed_out="$(docker start -a "$sid")"
-zt_url="$(printf '%s\n' "$seed_out" | sed -n 's/^ZAAKTYPE_URL //p' | head -1)"
-iot_url="$(printf '%s\n' "$seed_out" | sed -n 's/^INFORMATIEOBJECTTYPE_URL //p' | head -1)"
 docker rm -f "$sid" >/dev/null
-[ -n "$zt_url" ] || { echo "ERROR: seed did not report a ZAAKTYPE_URL" >&2; exit 1; }
-[ -n "$iot_url" ] || { echo "ERROR: seed did not report an INFORMATIEOBJECTTYPE_URL" >&2; exit 1; }
-echo ">> zaaktype: $zt_url"
-echo ">> informatieobjecttype: $iot_url"
+printf '%s\n' "$seed_out" | grep -q '^ZAAKTYPE_URL ' || { echo "ERROR: seed did not publish the zaaktype" >&2; exit 1; }
 
-echo ">> recreating the acl service pointed at the seeded zaaktype + informatieobjecttype (host-consistent)"
-ACL_ZAAKTYPE_URL="$zt_url" ACL_INFORMATIEOBJECTTYPE_URL="$iot_url" ACL_OPENZAAK_BASEURL="$oz_base/" \
-  docker compose -f "$compose" up -d acl
+# The ACL resolves the zaaktype + informatieobjecttype by identificatie/omschrijving (S-27, ADR-0021),
+# so there is no URL to inject — only the OpenZaak base URL, pointed at the same host's container IP
+# (OpenZaak rejects a single-label host on zaak-create).
+echo ">> recreating the acl service pointed at OpenZaak's IP (it resolves the zaaktype itself, S-27)"
+ACL_OPENZAAK_BASEURL="$oz_base/" docker compose -f "$compose" up -d acl
 WAIT_TIMEOUT="${WAIT_TIMEOUT:-120}" bash "$here/wait-healthy.sh" acl
 
 echo ">> submitting a registration to the domain"