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

docs/architecture/adr-0021-acl-resolves-zaaktype-by-identificatie.md

@@ -0,0 +1,67 @@
+# ADR-0021: The ACL resolves its zaaktype by identificatie, not a pinned URL
+
+- **Status:** Accepted
+- **Date:** 2026-07-22
+- **Deciders:** Respellion engineering
+- **Relates to:** S-27 (#113), proposed in #117. The cleaner design deliberately split out of S-B04
+  (#110, ADR-0020), which fixed the local stack with an infra-only bootstrap.
+
+## Context
+
+The ACL was handed a **pinned zaaktype URL** (`Acl__Defaults__ZaaktypeUrl`) and diploma
+informatieobjecttype URL. OpenZaak assigns those UUIDs at creation, so the URL is not knowable when
+the compose file is written — every stack had to seed the catalogus and then capture + inject the
+resulting URLs out of band: `run-domain-check.sh` for CI, and the `local-seed` → `acl.env` bootstrap
+(ADR-0020) for `make local`. Brittle, and a stale/placeholder URL failed opaquely (OpenZaak 400).
+
+## Decision
+
+**The ACL resolves its zaaktype (by `identificatie`) and diploma informatieobjecttype (by
+`omschrijving`) from OpenZaak's Catalogi API, instead of being handed the URLs.**
+
+- **Config:** `AclDefaults.ZaaktypeUrl`/`InformatieobjecttypeUrl` → `ZaaktypeIdentificatie`
+  (`BIG-REGISTRATIE`) / `InformatieobjecttypeOmschrijving` (`Diploma`).
+- **Lookup (gateway, §8.1):** `GET /catalogi/api/v1/zaaktypen?status=definitief&identificatie=…` →
+  the published zaaktype URL; `GET /catalogi/api/v1/informatieobjecttypen?status=definitief` matched
+  on `omschrijving`. Reuses the gateway's existing catalogus-query machinery.
+- **Timing = lazy + cached (`CachedZaaktypeCatalog`).** Resolve on first use (first zaak open /
+  document store) and cache for the process lifetime. Lazy avoids a startup ordering coupling — the
+  ACL never crash-loops when it boots before the catalogus is published. A **failed** resolution is
+  not cached, so it is retried on the next call (e.g. once the zaaktype is published); a restart
+  re-resolves.
+- **Failure mode:** no published match → a clear "No published zaaktype with identificatie '…' found
+  in OpenZaak — is the BIG catalogus seeded and published?" error, replacing the opaque placeholder
+  400.
+
+## Consequences
+
+**Positive**
+
+- No stack captures or injects a server-assigned URL any more: `run-domain-check.sh` drops the
+  `ACL_ZAAKTYPE_URL`/`ACL_INFORMATIEOBJECTTYPE_URL` capture+inject, `docker-compose.yml`/`.local.yml`
+  drop the placeholder URL env, and `local-seed`/`acl.env` shrink to a single line. The ACL
+  self-configures from the catalogus it already talks to.
+- The failure mode is legible (a named error instead of a 400 on a zeros-UUID).
+
+**Negative / costs**
+
+- The ACL still needs its OpenZaak **BaseUrl** pointed at a **URL-valid host (a container IP)**, so
+  the base-URL injection from ADR-0020 stays (the local `acl.env` now carries only that; CI keeps
+  `ACL_OPENZAAK_BASEURL`). This is **not** something S-27 can remove: OpenZaak validates the
+  `zaaktype` field on zaak-create with Django's URLValidator and **rejects a single-label host**
+  (`http://openzaak:8000/…` → `zaaktype: bad-url, "Voer een geldige URL in."`, confirmed empirically).
+  So ADR-0020's `seed-env` volume + ACL entrypoint shim are **simplified, not deleted**.
+- New branching in the gateway/resolver → unit + integration test surface; the mutation ratchet
+  covers it (§5).
+- A seed step still **creates + publishes** the zaaktype (this ADR changes only discovery). Reaching
+  OpenZaak's Catalogi API to *seed* likewise needs the IP host (its query params hit the same
+  URLValidator) — unchanged from before.
+
+## Alternatives considered
+
+- **Resolve at startup** (eager). Simpler cache, but reintroduces the ordering coupling (crash-loop
+  if the catalogus isn't published yet). Rejected in favour of lazy.
+- **Per-request resolution** (no cache). No stale-cache risk, but a Catalogi lookup on every ACL
+  operation. Rejected; a process-lifetime cache with restart-to-refresh is enough here.
+- **Keep the pinned URL** (status quo / ADR-0020 only). Rejected — the brittleness this ADR removes is
+  exactly what S-27 was carved out to fix.

docs/demo-script.md

@@ -26,9 +26,31 @@ make verify-local     # → "OK — a fresh local stack completed the flow with
 #    test123); it shows as INGESCHREVEN in the openbaar register at http://localhost:8141.
 ```
 
-> The zaaktype UUID is server-assigned, so `local-seed` writes the real URL into a shared volume as
-> `acl.env` and the ACL sources it on startup (ADR-0020). The cleaner long-term fix — the ACL
-> resolving its zaaktype by `identificatie` — is tracked separately as S-27 (#113).
+> The zaaktype is discovered by the ACL itself since S-27 (below); `local-seed`'s `acl.env` now
+> carries only OpenZaak's IP base URL, which the ACL still needs because OpenZaak rejects a
+> single-label host on zaak-create (ADR-0020 + ADR-0021).
+
+---
+
+## S-27 — ACL resolves its zaaktype by identificatie, not a pinned URL (#113, ADR-0021)
+
+**Outcome:** the ACL discovers its BIG zaaktype (by `identificatie`) and diploma informatieobjecttype
+(by `omschrijving`) from OpenZaak's Catalogi API, instead of being handed the server-assigned URLs.
+No user-visible behaviour change — the flow runs exactly as before — but no stack captures/injects a
+zaaktype URL any more, and a missing catalogus now fails with a clear message instead of an opaque 400.
+
+```bash
+# The live ACL↔OpenZaak integration test proves resolution against a real seeded OpenZaak:
+make verify-acl     # → "resolves the published BIG-REGISTRATIE zaaktype + Diploma informatieobjecttype by business key"
+
+# End-to-end unchanged (the ACL self-discovers the zaaktype during the flow):
+make verify-local   # local stack — still green, now with no zaaktype-URL injection
+make verify-domain  # CI stack — recreates the ACL pointed only at OpenZaak's IP (no URL to inject)
+```
+
+> The ACL still needs its OpenZaak base URL at a URL-valid host (a container IP): OpenZaak's
+> URLValidator rejects a single-label host like `openzaak:8000` on zaak-create. So ADR-0020's base-URL
+> injection stays; only the zaaktype/informatieobjecttype **URL** injection is gone (ADR-0021).
 
 ---