DSO / Ozon ingest

DSO (Digitaal Stelsel Omgevingswet) is de meest architectuur-consequente bron en de zwaarste ingest. Een omgevingsplan heeft article-tree-structuur, IMOW kernklassen voor activity / location / norm binding, en meerdere voorkomens per regeling. De ontwerp-vragen lopen tegen vier dingen tegelijk aan: FRBR Work/Expression/Manifestation modellering, ADR-0027 bitemporal dso_artikel, IMOW kernklassen-modellering, en de cross-stack bridge naar canonical.publications.

Volledige problem statement: docs/handoffs/2026-05-05-dso-ozon-problem-statement.md. Hieronder de essentie.

De empirische schaal (2026-05-05)

Tabel	Rijen	Opmerking
canonical.dso_regeling	68	11 Omgevingsplan, 22 Voorbeschermingsregels, 14 Programma, 7 Visie, 6 AMvB, 3 Waterschapsverordening, ...
canonical.dso_artikel	41.797	Over 57 distincte regelingen. Grootste: mnre1034/2018/BWBR0041330 (6.911 artikelen — een Ministerie-regeling die niet echt in dso_regeling thuishoort, zie open vraag)
canonical.dso_regelvooriedereen	15.314	Eén van drie IMOW JuridischeRegel-subtypes
canonical.dso_instructieregel	1.985	Idem, met instrumenten TEXT[] als enige variant-veld
canonical.dso_omgevingswaarderegel	95	Idem
canonical.dso_activiteit	n.b.	activity-laag
canonical.dso_gebiedsaanwijzing	n.b.	area-designations
canonical.instruments WHERE key_kind='akn'	244	FRBR Work-projectie van DSO; slechts 30 (12.3%) heeft dso_regeling-rij — pointer-mismatch

Twee parallelle ingest-paths

DSO komt vandaag binnen via twee paden die niet zijn geünificeerd:

1. Ozon path — OzonSyncService.ts schrijft naar gestructureerde satellieten (dso_regeling, dso_artikel, IMOW kernklassen, dso_locatie). Doet structureel het juiste (typed tabellen, normalized geometries, idealisatie-carry) maar met drie problemen:

• ON CONFLICT DO UPDATE SET inhoud overschrijft artikel-tekst per #4158 — zie bitemporal
• IMOW satelliet-extractie is inconsistent — gm1721 (Bernheze) heeft 0 rule-subtypes
• Heeft alleen op 68-regeling canary-subset gerund

2. Discovery path — schrijft naar canonical.documents met source='Ruimtelijkeplannen' of source='DSO', mostly titles-only shells (~8.000 rijen). Issue #4165 — discovery path moet stoppen met naar canonical.documents schrijven.

Wat het FRBR-ontwerp wil: Ozon is het system of record voor DSO-content. Discovery path is alleen voor URL-enumeratie. instrument_versions.content_refs voor AKN-instruments wijst naar dso_regeling/dso_artikel, niet naar canonical.documents.

Tien open ontwerp-vragen

1. Voorkomen-naar-instrument_version mapping. Eén row per voorkomen, of collapse op article-content-identiek? 22 van 68 regelingen hebben meerdere voorkomens (gemiddelde 2.06, max 10).
2. content_refs.store voor AKN-instruments. Vandaag wijst hij naar canonical.documents (244 rijen). Pointer-method wil naar dso_regeling. Backfill of dual-reference tijdens transitie?
3. IMOW kernklasse temporaliteit. ADR-0027 v1 maakt alleen dso_artikel bitemporal; satellieten blijven current-snapshot. Bij wijzigingsbesluiten waarin artikel-activiteit-binding wijzigt mist current-snapshot historie. Bitemporal-vanaf-dag-1 voor satellieten?
4. Rule-subtype tabellen: parallelle vs unified. ADR-0025 koos parallel tabellen. Geen evidence voor of tegen na 3 jaar — gm1721 heeft 0 rijen in alle drie; data van gm0772 nodig.
5. dso_regeling vs FRBR instruments: wie is canonical? Twee paden: (a) beide houden, dso_regeling houdt source-specific metadata, FRBR is cross-source identity layer; (b) alles naar instruments + entity_terms + dso-JSONB. Pointer-method gaat voor (a).
6. Cross-regeling IntRef resolution. STOP <IntRef ref="..."> kan binnen-regeling, andere-regeling, of extern (BWBR via AKN) targeten. Vandaag: alleen intra-regeling resolved. Met FRBR instruments als cross-source identity layer: eager-at-ingest (breekt bij missing targets) vs lazy-at-query (slower maar always correct)?
7. TAM en tijdelijk-deel lineage. Een TAM-regeling (mnre1034/2023/OOWVbbLSDD3TijdelijkDeel*) overlay-t meerdere gemeente-omgevingsplannen. Eigen Work in FRBR, of amendment via instrument_lineage? Gm1721 heeft drie TAMs — geen cross-link gemodelleerd vandaag.
8. National-level regelingen in dso_artikel. Grootste is mnre1034/2018/BWBR0041330 (6.911 artikelen) — een BWBR-anchored Ministerie regeling in de DSO satellite. Hoort dit in public.law_articles (BWBR-side) en geprojecteerd via Wetgeving-canary, OR in dso_regeling/dso_artikel omdat DSO Presenteren het exposed? Vandaag: beide stores = duplicate truth.
9. NL-wide enumeration strategie. 68 regelingen is canary; NL-wide is low thousands. Catalogus API geeft lijst; crawl vanaf daar of trigger uit OB-bekendmakingen? Rate-limits matter (Ozon enforced, sustained 429s bij overrun).
10. Change-detection op re-sync. ADR-0027 wil content-fingerprint (md5(inhoud)) vervangend voor ON CONFLICT DO UPDATE. Bij 1.000-4.000 artikelen × duizenden regelingen → miljoenen vergelijkingen per full-resync. Cheaper: voorkomen tijdstipRegistratie eerst vergelijken; fingerprint alleen bij voorkomen-progressie.

Constraints die niet meer ter discussie staan

• Pointer-method is de architectuur. Article-level cross-document modeling wordt NIET geünificeerd.
• canonical.dso_artikel is de article-level store voor DSO. Artikel-tekst blijft daar; verschuift niet naar instrument_versions.full_text.
• canonical.documents is legacy en sterft in Phase 5.
• ADR-0011 ingest/enrichment-split staat. LLM-shaped werk (rectificatie classifier, judicial-effects extractor) leeft achter enrichment-boundary, niet op Ozon hot path.
• Geometries: EPSG:28992 opslag, EPSG:4326 serve (ADR-0028).
• IMOW satellite-tabellen blijven parallel (ADR-0025) tenzij brainstorm specifieke evidence levert.

Worked-example: gm1721 (Bernheze)

/akn/nl/act/gm1721/2020/omgevingsplan — Omgevingsplan gemeente Bernheze. Drie voorkomens. Voorkomen 3 latest (beginInwerking=2024-12-06).

Vandaag in DB:

• canonical.dso_regeling row 996 — header
• canonical.dso_artikel 1.361 rijen
• canonical.dso_activiteit 90 rijen
• canonical.dso_locatie 1 rij
• Alle drie rule-subtype tabellen: 0 rijen
• canonical.instruments 1 rij (key_kind=akn)
• canonical.instrument_versions 1 rij — drie voorkomens gecollapsed in één row; valid_from='2020-01-01' is fictief (AKN-jaar, niet werkelijk voorkomen-datum); content_refs wijst naar legacy canonical.documents
• canonical.publications.refers_to_instrument_version_id voor deze rij: 0 — geen OB-cross-link

Wat het nieuwe ontwerp wil:

• 3 instrument_versions-rijen (één per voorkomen) met valid_from afgeleid van beginInwerking, content_refs naar dso_regeling
• 3 instrument_renderings-rijen (één per voorkomen) wijzend naar AKN-XML download URL
• dso_artikel bitemporal append-only — artikelen waarvan inhoud wijzigde krijgen nieuwe rij
• IMOW-tabellen ge-populated per voorkomen
• OB-bekendmakingen geprojecteerd naar canonical.decisions + canonical.publications met refers_to_instrument_version_id ingevuld

Het gat tussen de twee plaatjes is het werk.

Onderliggende docs

• docs/handoffs/2026-05-05-dso-ozon-problem-statement.md — volledig design-brief
• ADR-0025 / 0026 / 0027 / 0028 — DSO-specifieke beslissingen
• ADR-0031 / 0032 — FRBR foundations + migration plan
• src/server/adapters/dso/ozon/OzonSyncService.ts — Ozon-writer code
• src/server/adapters/dso/StopTpodExtractor.ts — STOP-XML extractie