Wrong-turn ledger

Een lopend overzicht van architecturale wrong turns en hoe ze worden ontmanteld. Niet om naming-and-shaming, maar omdat een toekomstige lezer die de huidige structuur ziet anders niet kan reconstrueren waarom bepaalde keuzes zijn gemaakt — namelijk omdat ze afwijken van eerdere keuzes die fout bleken.

Onttrokken uit de architecture audit van 2026-05-05 (docs/handoffs/2026-05-05-architecture-audit.md §6), aangevuld met opvolg-bevindingen.

Schema-niveau wrong turns

Wrong turn	Status
Eén platte canonical.documents tabel voor elk document-type. De originele zonde en de reden dat we FRBR doen.	Wordt ontmanteld via strangler-fig migration (ADR-0032). Start van Phase 2 (2026-05-05).
Single-column document_type op instruments en decisions. Geprobeerd; vervangen door vier-axis polymorphic entity_terms per #4114 + ADR-0030.	Vervangen. Origineel column gedeprecieerd in design v1 §4.11.
canonical.documents als persistence target voor DSO discovery hits. Geprobeerd; reverted in CAN-016 — DSO discovery schrijft nu naar canonical.discovery_refs, niet de canonical document store.	Reverted.
<Tekstdeel> als document-type. Eerdere sketches behandelden DSO Tekstdelen als hun eigen canonical document class. Nu: geneste artikel-rijen onder dso_artikel met node_type = ARTIKEL/HOOFDSTUK/....	Correct opgelost — de bigger wrong turn zou geweest zijn om parallelle typed tables te expanderen.
besluit_kind draagt zowel procedurele lifecycle als content-type. Vroege drafts hebben ze gemengd; live-data-validatie duwde content-type naar entity_terms, liet besluit_kind als lifecycle-only.	Half opgelost; volledige axis-split nog open — zie besluit-soort-axis.
Rectificaties amenden alleen decision_expressions. Gefalsifieerd: 100 van 135 rectificaties (74%) targeten instrument-stack content, niet decision-stack.	Fix: target_kind ∈ {decision, instrument, both} op de rectificatie-junction. Moet landen vóór WI-FRBR-014.

Identity / corpus wrong turns

Wrong turn	Status
ECLI-suffix-is-numeric aanname. 1.194 van 5.907 ECLIs (20%) gebruiken pre-2013 LJN-style alphanumerieke suffixes. Regex in WetgevingXmlExtractor.ts:296 was te smal.	Gefixt in PR #4145.
78% authority-resolution coverage claim. Reproduceerde niet live (35.6% exact / 66.6% case-insensitive / 96.6% substring).	WI-FRBR-013 backfill landde op empirisch 94.9% structurele coverage. Residual is naam-variant ruis.
OB rectificatie / IMRO "dual-platform" hypothese. F8: 168 same-(plan_identifier, plan_version) pairs leken DSO + ruimtelijkeplannen.nl.	Gecorrigeerd: 139 van 168 zijn same-URL-double-ingest bug — twee ingest-paths hitten dezelfde URL. Migratie moet (plan_id, plan_version) mergen tot 1 Work + 1 Version + 2 Renderings.
canonical.documents WHERE source='Wetgeving' (4.412 rijen) was eigenlijk OB.	Mislabelled bij ingest. WI-FRBR-026 is de cleanup; pre-Phase-4 prerequisite — strangler view zou ze anders weeshalen.
canonical.documents WHERE source='Ruimtelijkeplannen' (7.111 rijen) — 7.321 met source_metadata.sourceType='DSO' zijn eigenlijk DSO discovery shells.	Issue #4165 — discovery path moet ophouden in canonical.documents te schrijven; canonical.discovery_refs is het nieuwe target.

DSO-stack wrong turns

Wrong turn	Status
dso_locatie.geometry opslaan als 4326 in plaats van 28992. 5.669 mislabelled rijen.	Gevangen in mig 127; ADR-0028 standardiseert op RD-opslag, WGS84-serve.
ON CONFLICT DO UPDATE SET inhoud in OzonSyncService.ts:337-340. Overschrijft artikel-tekst die de FRBR-versie-pointer moet binden.	ADR-0027 (bitemporal append-only dso_artikel) moet eerst landen. Explicit Phase 0a sequencing in ADR-0032. Zie bitemporal.
kwalificatie als TEXT zonder enum-constraint op dso_activiteit_locatie. Vijf bekende waarden (verbod / vergunningplicht / meldingsplicht / informatieplicht / toegestaan); niet enforced.	Minor — moet CHECK-constraint worden.
WI-FRBR-016 OP-XML legacy body parser. Loste een niet-bestaand probleem op. Pre-2024 OB rijen hebben alleen IMRO-regex-extractie nodig (al in pattern-bank) plus decision-stack-projectie.	Dropped 2026-05-04, ~12h bespaard.

Architectuur wrong turns

Wrong turn	Status
First-4K-chars LLM extraction. ADR-022 doodde dit na NER-pre-filter-recall-caps. De oorspronkelijke diagnose was "verkeerde NER model"; de werkelijke fout was de hele document als één LLM-call behandelen.	Vervangen.
Whole-document LLM enrichment op de ingest hot path. ADR-0011 split ingestion van enrichment. LLM-shaped werk leeft achter de enrichment-boundary.	Opgelost.
Mongo-era full-document XML pipeline producerend canonical_documents.fullText.	Vervangen door typed Postgres-tabellen in ADR-0025.
External jurist contractor voor legal validation. Reframed (2026-05-04) — empirische validatie tegen public.law_articles (9.818 artikelen) plus corpus-sampling volstaat.	WI-FRBR-025 nieuwe framing aangenomen.
KG attachment chain v0 (lex → akn → eli → metalex). Damp — parents waren niet geladen in GraphDB.	Vervangen door TOOI-direct + ELI single parent.
Legacy src/server/services/knowledge-graph/ (~79 files). Deprecated by ADR-018; module-by-module triage in ADR-023 (Delete / Backlog / SHACL-port / SPARQL-port).	Ongoing triage.

Lessen

Vier patronen blijven terugkomen in deze ledger:

1. Aannames die niet tegen live data zijn getoetst (78% resolution, dual-platform, ECLI-numeric, first-4K extractie). Conclusie: feedback_verify_dont_guess — voor data-bevattende ontwerpen, query de DB voordat het ontwerp wordt opgeschreven.
2. Enum-axes die door elkaar worden gehusseld (besluit_kind lifecycle+content, document_type single-axis-vs-polymorphic). Conclusie: splits enums per onafhankelijke axis (feedback_pattern_category_tagging toegepast op closed-vocab-design).
3. Pijler-scheiding ondergraven door polymorphic-FKs (canonical.documents als universal target, polymorphic-fix op publicatie.publicaties). Conclusie: het oude flat-table-anti-pattern keert in subtieler vorm terug zodra je een polymorphic-FK-shortcut accepteert.
4. Architectuur-claims zonder corpus-validatie (de "78%" claim, het Phase-1-vs-Phase-0+1 attribution slip). Conclusie: ankering tegen corpus is niet alleen voor catalogus-rijen — ook voor architectuur-rapportages.

Onderliggende docs

• docs/handoffs/2026-05-05-architecture-audit.md §6 (wrong-turn ledger origineel)
• docs/handoffs/2026-05-05-architecture-audit-corrections.md (empirische correcties)
• docs/24-research/2026-05-04-frbr-design-falsification/FINDINGS.md (F1-F8 falsifications)