feat(openzaak): bounded retry + flagged write divergence (WP-60)

Local aanvraag/document writes and their paired ZGW writes aren't
transactional; a ZGW failure after the local write succeeds used to
diverge silently. ZgwHttpClient now retries transport-shaped failures
(not 500, which can follow a partial commit on the non-idempotent
statussen/rollen POSTs), and a ZGW failure that survives retry sets
Aanvraag.ZgwError plus a zgw:divergence audit row instead of failing
or diverging quietly. No outbox/reconcile job: three request-triggered
write paths don't justify a persisted queue that would also need to
carry citizen PII for the JWT audit claims.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

docs/reference/architecture/0005-openzaak-behind-bff.md

@@ -67,5 +67,13 @@ up front — the migration stance ADR-0001 already prescribes.
 - **Also shipped (WP-50):** `IZaakSource.CreateZaak` — the first write. Submitting an aanvraag
   now also creates a Zaak + Status + Rol in OpenZaak when `Zgw:Enabled=true`, routed through the
   existing submit endpoint with zero DTO change (same seam, same anti-corruption boundary).
-- **Deferred:** real inbound OIDC/JWT auth (still header-stubbed), Documenten/DRC upload + link
-  (WP-51), Notificaties/NRC webhooks (WP-52), adding OpenZaak to docker-compose.
+- **Also shipped (WP-51):** `IDocumentSource` (`LocalDocumentSource`/`OpenZaakDocumentSource`,
+  same config-gated seam shape) — an upload registers a Documenten/DRC enkelvoudiginformatieobject
+  and, once a zaak exists, a submit links it in with a zaakinformatieobject.
+- **Also shipped (WP-60):** bounded retry in `ZgwHttpClient` for transport-shaped ZGW failures,
+  plus a flagged (not silent) divergence — `Aanvraag.ZgwError` + a `zgw:divergence` audit row —
+  when a ZGW write still fails after retry. No outbox/background worker (see WP-60 for the
+  ladder check that ruled it out for this POC's write volume).
+- **Deferred:** real inbound OIDC/JWT auth (still header-stubbed), Notificaties/NRC webhooks
+  (WP-52, shipped instead as a direct-to-BFF delivery in WP-58), adding OpenZaak to
+  docker-compose, an automated reconciliation/repair job for a flagged divergence (WP-60).

docs/reference/openzaak-integration.md

@@ -61,11 +61,51 @@ The created zaak's `identificatie` becomes the returned `Referentie`; its status
 same coarse `InBehandeling` shape `ZgwZaakMapper` already uses for a freshly-opened zaak
 (`ZgwZaakMapper.ToCreatedStatusDto`).
 
-ponytail shortcuts, marked at the call sites: (a) "first statustype/roltype Catalogi returns"
-rather than a fully-configured per-type map — fine while a zaaktype has exactly one initial
-status and initiator role; (b) no compensating transaction — if any ZGW call throws, the
-aanvraag is already `Submitted` locally with no matching zaak (acceptable for a demo backend;
-a production arc needs retry/reconciliation or an outbox before trusting this dual-write).
+ponytail shortcut still standing: "first statustype/roltype Catalogi returns" rather than a
+fully-configured per-type map — fine while a zaaktype has exactly one initial status and
+initiator role. The "no compensating transaction" gap this section used to flag here is closed
+by WP-60 — see "Write resilience" below.
+
+## Write resilience (WP-60)
+
+The local write (`ApplicationStore.Submit`, `DocumentStore.Add`/`Link`) and its paired ZGW
+write aren't transactional — this section covers what happens when the ZGW half fails after the
+local half already committed, closing the one gap the sections above used to flag as needing
+"retry/reconciliation or an outbox" before this integration could be called production-ready.
+Deliberately **not** an outbox: three write paths, each triggered by exactly one interactive
+request, don't justify a persisted queue (which would also need to carry the acting citizen's
+BSN for the JWT's audit claims — PII in a new table) — see WP-60 for the full reasoning.
+
+- **Bounded retry, in `ZgwHttpClient`.** Every ZGW call gets up to 3 attempts (200ms, doubling)
+  on transport-shaped failures — 429/502/503/504/408, connection errors, timeouts — with a
+  fresh request and JWT per attempt (a sent request/content can't be resent). **500 is
+  deliberately not retried**: it can follow a partial commit on the two non-idempotent POSTs
+  (`/statussen`, `/rollen`), so retrying risks a duplicate write. The create-zaak/document POSTs
+  are additionally safe to retry because OpenZaak enforces uniqueness on
+  (`bronorganisatie`, `identificatie`) — and WP-50/51 already set `identificatie` to the
+  locally-generated reference/document id, so a retry after a lost response 400s instead of
+  duplicating.
+- **The local write is never rolled back.** Un-submitting a local aanvraag after a partial ZGW
+  failure (e.g. the zaak POST succeeded but `/statussen` didn't) would let the citizen resubmit
+  under a _new_ reference, orphaning the first zaak — worse than leaving it flagged.
+- **A caught ZGW failure is flagged, not silent.** `Program.cs`'s submit endpoint wraps
+  `CreateZaak` and `LinkToZaak` in separate try/catches (separate so a create-zaak failure
+  doesn't also skip the still-local document link) and, on catch, logs the error, sets
+  `Aanvraag.ZgwError` (non-null = "the ZGW side of this submit didn't complete"), and records a
+  `zgw:divergence` audit row (same `AuthzAuditStore` trail every other decision uses, visible at
+  `/beheer/audit`) — see `RecordZgwDivergence`. The endpoint still returns 200 with the local
+  reference/status: that's truthful (the reference _is_ what would become the zaak's
+  `identificatie`) and never branches on `Zgw:Enabled` (an offline `LocalZaakSource` never
+  throws, so the catch is dead code there).
+- **The document upload path flags differently.** `OpenZaakDocumentSource.Upload` catches its
+  own ZGW failure (config gap or transport) and logs it, but doesn't set a separate flag column
+  — `DocumentStore.Get(id).DrcUrl == null` is already the meaningful "not registered in ZGW yet"
+  detector `LinkToZaak` skips on, so no second mechanism is needed for that half.
+- **Repair.** No automated reconcile job exists yet — a flagged zaak is repairable on demand
+  because its (would-be) `identificatie` always equals the aanvraag's `Referentie`, so a future
+  admin action can `GET /zaken?identificatie=...` and either adopt the existing zaak or retry
+  `CreateZaak`. Deferred until a second write pair (WP-66) or a real deployment makes it worth
+  building — at which point the outbox question above is also worth re-asking.
 
 ## Documenten / DRC upload + zaak link (WP-51)
 
@@ -88,8 +128,11 @@ happens first — it stays the record of truth for preview/download/audit regard
 `ZgwHttpClient` (shared GET/POST-with-bearer-JWT plumbing) was factored out of
 `OpenZaakZaakSource` once `OpenZaakDocumentSource` needed the identical boilerplate.
 
-ponytail shortcut: `vertrouwelijkheidaanduiding` is hardcoded to `"openbaar"` — a per-category
-confidentiality level would matter for production but isn't needed to prove the seam.
+`vertrouwelijkheidaanduiding` is driven by a per-document-type stamdata table (WP-59,
+`Stamdata/documentconfidentialiteit.json`, ADR-0004), falling back to `"openbaar"` for any
+category absent from it. Unlike the zaak side, an upload's ZGW failure (past
+`DocumentStore.Add`) is caught and logged rather than persisted as a separate flag column —
+see "Write resilience" below for why the two write paths differ.
 
 ## The ZGW client (`backend/src/BigRegister.Api/Zgw/`)