register-referentie/docs/architecture/adr-0030-projection-sourced-from-the-register.md

# ADR-0030: The read projection is sourced from the register, not from ZGW

- **Status:** Accepted
- **Date:** 2026-08-28
- **Deciders:** Respellion engineering
- **Slice:** S-19b-2 (#153), second of the S-19b (#150) split
- **Builds on:** ADR-0008 (read projection store), ADR-0028 (Objecten holds the register), ADR-0029 (Objecten publishes to NRC)

## Context

ADR-0028 moved the authoritative register record into the Objecten API, and said what should
follow: "the read projection can become a cache of Objecten rather than a re-derivation of
ZGW." Until this slice it was still the latter — the Event Subscriber listened on the `zaken`
kanaal and inferred register state from case events:

- a `zaak`/`create` meant INGEDIEND;
- any `status`/`create` was taken to be the approval, so meant INGESCHREVEN — the subscriber
  may not read OpenZaak (§8.1), so it could not tell one statustype from another;
- the citizen-facing reference was not in the notification at all, so every projection had a
  second hop: ask the ACL for the zaak's identificatie (#78).

So the register — a fact about a person — was reconstructed by guessing at the lifecycle of the
case that happened to produce it. ADR-0029 made the register itself publish. This ADR switches
the projection over to it.

## Decision

**The Event Subscriber listens on the `objecten` kanaal and projects the `RegisterRecord` the
notification points at. The projection is a cache of the register; ZGW is no longer a source.**

- The subscriber's abonnement moves from `zaken` to `objecten` (`register-abonnement.py`, and
  the CI projection check).
- An Objecten notification carries **no record data** — only the object URL and the objecttype
  as a kenmerk — so the record is read back through the ACL (`POST /register-records/read`).
  §8.1 applies to Objecten exactly as ADR-0028 established: the ACL is the only code that talks
  to it.
- The accepted acties are `create`, `update` and `partial_update`. The last one is not
  defensive breadth: the ACL upserts with PATCH, and DRF routes a PATCH through the notifying
  `update()` while naming the action `partial_update` — which is what Objecten publishes. So
  every approval arrives as `partial_update`, and accepting only `create`/`update` drops the
  one state change this slice exists to project. `destroy` is deliberately not accepted:
  removing a registration from the public register is its own decision.
- The record already carries `id`, `status` and `reference`, so the row is the record. The
  zaak-shaped surface goes: `IsZaakCreated`, `IsZaakStatusSet`, `ZaakUrl`, `ZaakId`, and
  `ToEntry`'s `Resource == "status"` inference are replaced by `IsRegisterRecordWritten` +
  `ObjectUrl`, and the ACL enrichment hop disappears.

### The ACL writes an INGEDIEND record on submit

Before this slice only approval wrote a record, so re-sourcing alone would have silently
dropped every INGEDIEND row from the public register. `OpenZaakAsync` therefore upserts a
record with status INGEDIEND after opening the zaak, keyed on the same zaak id that approval
later upserts to INGESCHREVEN.

This is the same two-writes-converging posture ADR-0028 already accepted for approval, now on
the submit path too: both writes are idempotent, so a retried submit updates the record rather
than adding a second one (§8.6). The reference comes from the registration itself, so unlike
approval this path needs no ZGW read-back.

The alternative — a register holding only INGESCHREVEN — is arguably the more correct reading
of "public register", but it narrows what the openbaar portal shows and reads against PRD §68
("~50 register entries with diverse statuses"). Rejected as a behaviour change this slice was
not asked to make.

### The dedup key is the projected row, not the notification

NRC carries no notification id and may redeliver, so the idempotency key is derived from
content (as before). The obvious candidates both break here:

- **the object URL alone** — the ACL upserts *one object per registration*, so submit and
  approval notify about the same URL, and the approval would be swallowed as a duplicate;
- **object URL + actie** — a retried approval is a second `update`, so it would be dropped
  while genuinely being the same state (harmless), but a *third* distinct state would collide
  with it (not harmless).

The key is therefore the object plus the state that write puts in the projection —
`objecten:object:{url}:{status}:{reference}`. A redelivery collapses; a genuine state change
does not. That is exactly the property §8.6 asks for, and it needs no version field from
Objecten's internals.

### The notification log holds the row, not the event

`processed_notifications` stops describing ZGW events (`actie`, `zaak_id`, `resource`) and
holds the projected row itself (`register_id`, `status`, `reference`). A rebuild becomes a
replay with no mapping rules and no upstream reads at all — §8.4 held before via the ACL hop;
now it holds outright.

The migration **drops** the old columns rather than renaming them. EF scaffolded renames
(`resource` → `register_id`, `zaak_id` → `status`) that would have carried ZGW values into
columns meaning something else entirely, and a rebuild would then have projected that garbage.

- ponytail ceiling: the migration empties both tables. A pre-slice row describes a zaak event
  the new projector cannot reproject, and the registrations behind those rows have no
  RegisterRecord in Objecten (only approvals wrote one), so they are not re-derivable from the
  new source either.
- Upgrade path: fine while stacks are ephemeral. If a long-lived environment ever needs to keep
  them, backfill by walking Objecten's objects rather than replaying the log.

## Consequences

**Positive**

- The register is read from the register. The projection is a derived cache of a first-class
  record, not an inference over someone else's lifecycle.
- The "any status-create is the approval" guess is gone — a real source of wrongness the moment
  the zaaktype grows a second statustype.
- One hop fewer per notification: the record carries its own reference, so the ACL enrichment
  call disappears.
- A rebuild needs nothing but its own log (§8.4).

**Negative / costs**

- Submission is now two writes across two modules and eventually consistent. A failure between
  them leaves a zaak with no register record until the submit is retried; nothing repairs that
  automatically yet — the same gap ADR-0028 recorded for approval, now on a second path.
- The projection lags the register by a notification round trip, where it used to lag the zaak
  by one. In practice the same order of magnitude.
- Projecting now depends on the ACL being reachable, where the reference enrichment used to be
  the only ACL dependency. A failed read means the notification is not logged and not
  projected — NRC retries, so it converges, but the failure mode is now on the main path.
- OpenZaak still publishes to `zaken` and nothing in the product listens. Kept because the
  `verify-nrc` check asserts that path, and turning off a working publisher to save nothing
  would be its own risk.

## Coupling rules touched (CLAUDE.md §8)

None bent. §8.1 holds — the subscriber reaches Objecten only through the ACL. §8.4 is
strengthened: the projection is rebuildable from its own log, with no upstream reads at all.
§8.6 is what the dedup-key discussion above is about.

## Verification

`make verify-projection` (`infra/run-projection-check.sh`, in CI's `verify-stack`) opens a zaak
**through the ACL** and asserts projection-api serves a row for it with status INGEDIEND — the
whole new chain in one assertion: ACL → Objecten → `objecten-celery` → NRC → `nrc-beat` →
Event Subscriber → projection → projection-api. A zaak created behind the ACL's back produces
no row, which is the re-source working rather than a gap.

`RegisterProjectieBijwerken.feature` covers the use case in business language, including the
approval case — the same row moving INGEDIEND → INGESCHREVEN, which is now one registration's
record being updated rather than two unrelated ZGW events.