De specificatie

De specificatie bestaat uit zes Markdown-documenten in spec/, naast de JSON-schema's en de verifier:

The specification

The specification consists of six Markdown documents in spec/, alongside the JSON schemas and the verifier:

IR-SPEC.md behandelt na methode en conventies de modellaag (hoofdstuk 2), de regellaag (3), de expressie- en conditielaag (4, verreweg het langste), stratificatie (5) en defaults (6), gevolgd door de WF-index; hoofdstukken 1, 7, 10 en 11 zijn nog skelet.

Mirror, then diverge

v0 is de getrouwe JSON-dump van de IR van regelspraak-java, op een vastgepinde commit en met al zijn eigenaardigheden. v1 wijkt bewust af waar de eerste review van die IR (spec/IR-REVIEW.md) aannames van Drools aanwees die in de IR terecht waren gekomen; zo wordt salience, de vuurprioriteit van een Drools-regel, gedeclareerde stratificatie. Elke afwijking is een geregistreerde delta in spec/CONSTRUCTS.md, "never a silent rewrite". De brekende afwijkingen zitten samen in het formaat uchar-ir-v1; een construct dat erbij komt, is een optionele uitbreiding (§ 2).

Spec-discipline

Elke voorschrijvende zin, normatief in de zin van standaarden, dus een MUST, vraagt een controleerbaar artefact:

After the method and the conventions, IR-SPEC.md covers the model layer (chapter 2), the rule layer (3), the expression and condition layer (4, by far the longest), stratification (5) and defaults (6), followed by the WF index; chapters 1, 7, 10 and 11 are still skeletons.

Mirror, then diverge

v0 is the faithful JSON dump of regelspraak-java's IR, at a pinned commit, warts included. v1 deviates deliberately where the first review of that IR (spec/IR-REVIEW.md) found Drools assumptions that had ended up in the IR; salience, the firing priority of a Drools rule, for example, becomes declared stratification. Every deviation is a tracked delta in spec/CONSTRUCTS.md, "never a silent rewrite". The breaking deviations are together in the uchar-ir-v1 format; a construct added to it is an optional extension (§ 2).

Spec discipline

Every normative sentence requires a checkable artifact:

De WF-index nummert de regels doorlopend, op 7 november 2026 van WF-001 tot en met WF-129. Een vervallen regel houdt zijn nummer en zijn rij in de index; zes regels zijn vervallen. Op vijf na heeft elke geldende regel een map in negative/: WF-008, WF-010 en WF-019 staan gemotiveerd OPEN, het rode corpus test WF-044 (§ 7), en WF-106 kan geen check hebben, omdat het formaat per objecttype maar één supertype toelaat.

The WF index numbers its rules consecutively, on 7 November 2026 from WF-001 through WF-129. A withdrawn rule keeps its number and its row in the index; six rules are withdrawn. All but five of the rules in force have a directory in negative/: WF-008, WF-010 and WF-019 are OPEN with a stated reason, the red corpus tests WF-044 (§ 7), and WF-106 cannot have a check, because the format allows only one supertype per object type.

Het constructenregister

spec/CONSTRUCTS.md is de scope-matrix van de IR, met één rij per construct. Het verdict is core, dialect, sugar, later(…), non-goal of een samengestelde vorm en legt het oorspronkelijke voorstel vast; wat geland is, staat in de delta-cel. "Kernel or sugar?" is de GHC-Core-vraag: heeft een construct een eigen kernelknoop nodig? Twee rijen, ingekort:

The construct register

spec/CONSTRUCTS.md is the scope matrix of the IR, with one row per construct. The verdict is core, dialect, sugar, later(…), non-goal or a composite form, and records the original proposal; what has landed is stated in the delta cell. "Kernel or sugar?" is the GHC Core question: does a construct need its own kernel node? Two rows, abridged:

Phase 4 en Phase 5 in deze rijen zijn fasen van het plan: het defaultmodel in de IR, en Catala als brontaal (spec/PLAN.md §6). Of een construct uitvoerbaar is, is in v1 een feit op IR-niveau: het heeft gespecificeerde semantiek, of het staat in het document als Unresolved, met zijn bron.

Phase 4 and Phase 5 in these rows are phases of the plan: the default model in the IR, and Catala as a source language (spec/PLAN.md §6). Whether a construct can be executed is, in v1, a fact at IR level: it has specified semantics, or it stands in the document as Unresolved, with its source.

Het wire-formaat

Een IR-document is JSON volgens spec/schema/uchar-ir-v1.schema.json, een casusbestand volgt uchar-case-v0.schema.json; beide zijn JSON Schema draft 2020-12, met een $id onder https://uchar.dev/schema/. Dat $id is een identificatie en resolveert (nog) niet. Een IR-document heeft vier verplichte topvelden, format, model (de declaraties), rules (een lijst per regelvorm) en diagnostics, en optioneel vocabularies (hoofdstuk 2.12). Elk object zet additionalProperties: false, elke knoop heeft een discriminator "node", en de namen van knopen, velden en enumeratiewaarden zijn Engels; gedeclareerde namen houden de taal waarin ze geschreven zijn:

The wire format

An IR document is JSON following spec/schema/uchar-ir-v1.schema.json, a case file follows uchar-case-v0.schema.json; both are JSON Schema draft 2020-12, with an $id under https://uchar.dev/schema/. That $id is an identifier and does not resolve (yet). An IR document has four required top-level fields, format, model (the declarations), rules (one list per rule form) and diagnostics, plus the optional vocabularies (chapter 2.12). Every object sets additionalProperties: false, every node has a "node" discriminator, and the names of nodes, fields and enumeration values are English; declared names keep the language they were written in:

Canonieke vorm

De dump is deterministisch: declaratievolgorde, getallen zonder exponent, \uXXXX voor niet-ASCII-tekens. Gate 2 leest elk ir.json in golden en red in met behoud van de getallexemen, schrijft het canoniek terug en eist byte-identiteit; zo verschijnt elk verschil tussen schema en emitter als een byteverschil. Daarnaast eist gate 2 dat elk object in golden, red en negative in de canonieke sleutelvolgorde van het schema staat.

Uitbreidingen, en velden zonder semantiek

Een uitbreiding van het formaat is een optioneel veld of een knoop, nooit verplicht en nooit null: ze staat er helemaal of niet. Een deel van die velden draagt geen semantiek, en geen uitvoerder mag er een uitkomst uit afleiden. Dat zijn de benamingen per vocabulaire (hoofdstuk 2.12), origin (hoofdstuk 2.13, WF-121), dat bij een element dat de frontend zelf maakte onder een naam die geen bron declareert, de vorm en de declaratie noemt waaruit het voortkomt, en op een Default de velden name, de naam die de bron aan het blok geeft, en statuteAnnotations, de // Bron:-regels boven het blok, één string per regel (hoofdstuk 6.1). Gate 13 haalt deze velden weg, of verwisselt en verschuift de benamingen, en eist dat ref, Clingo en beide takken van de Drools-backend dezelfde uitkomst geven. In het voorbeeld hieronder maakte de frontend een defaultsgroep voor de eigen uitzonderingen van het subtype Strandjutter op de geërfde regel meldtermijn:

Canonical form

The dump is deterministic: declaration order, numbers without an exponent, \uXXXX for non-ASCII characters. Gate 2 parses every golden and red ir.json while preserving the number lexemes, re-emits it canonically and requires byte identity; any difference between schema and emitter thus shows up as a byte difference. Gate 2 also requires every object in golden, red and negative to follow the schema's canonical key order.

Extensions, and fields without semantics

An extension of the format is an optional field or a node, never required and never null: it is written whole or not at all. Some of those fields carry no semantics, and no executor may derive an outcome from them. These are the designations per vocabulary (chapter 2.12), origin (chapter 2.13, WF-121), which, on an element the frontend made itself under a name no source declares, names the form and the declaration it comes from, and on a Default the fields name, the name the source gives the block, and statuteAnnotations, the // Bron: lines above the block, one string per line (chapter 6.1). Gate 13 removes these fields, or exchanges and rotates the designations, and requires ref, Clingo and both branches of the Drools backend to give the same outcome. In the example below the frontend made a defaults group for the subtype Strandjutter's own exceptions to the inherited rule meldtermijn:

Het vormanker heeft wel semantiek. Een knoop met anchor: "form" in het filter van een fold of in de toets van een kwantor leest het onderwerp van de vorm in plaats van het element, en de knoop IdentityCheck toetst of het element het onderwerp zelf is (hoofdstuk 4.1a, WF-122; in RegelSpraak "de X zelf"). Het vormanker is een voorlopig besluit, dat de maintainer kan terugdraaien.

Eenheden, toekenningen en afwezigheidsmarkers

De eenheid van een getal is een lijst factoren: elke factor is een Unit-knoop, met een gehele exponent waar die niet 1 is (hoofdstuk 2.5, WF-124). Hieronder is €/dg^2 de euro (EUR) maal de dag (dg) tot de macht −2. Een objectcreatie geeft het gemaakte object zijn waarden in assignments, een lijst MemberAssignment-knopen (hoofdstuk 3.3). Een attribuut met afwezigheidsmarkers heeft een eigen sum type met de constructors waarde, onbekend en niet van toepassing. PayloadAccess leest de waarde, en WF-127 eist dat die knoop onder een toets van zijn constructor staat (hoofdstuk 4.7).

The form anchor does carry semantics. A node with anchor: "form" in the filter of a fold or in the test of a quantifier reads the subject of the form instead of the element, and the node IdentityCheck tests whether the element is the subject itself (chapter 4.1a, WF-122; in RegelSpraak "de X zelf"). The form anchor is a provisional decision, which the maintainer can reverse.

Units, assignments and absence markers

The unit of a number is a list of factors: each factor is a Unit node, with a whole exponent where that is not 1 (chapter 2.5, WF-124). Below, €/dg^2 is the euro (EUR) times the day (dg) to the power −2. An object creation gives the created object its values in assignments, a list of MemberAssignment nodes (chapter 3.3). An attribute with absence markers has a sum type of its own with the constructors waarde, onbekend and niet van toepassing. PayloadAccess reads the value, and WF-127 requires that node to stand under a test of its constructor (chapter 4.7).

Casusbestanden

Een case*.json ligt naast een ir.json en bevat format, asOfDate, input en precies één van expected en expectedFault. Getallen zijn exacte lexemen in strings, nooit JSON-floats; wat in de invoer ontbreekt is leeg, en kenmerken beginnen onwaar. Een tijdlijn is een lijst segmenten met from (inclusief) en to (exclusief); een segment zonder from of zonder to heeft een open grens. Een verwachte tijdlijn wordt vergeleken in de canonieke vorm van RUNTIME-SEMANTICS hoofdstuk 3.1. Een afwezigheidsmarker staat er als {"constructor": "onbekend"}, een waarde van een attribuut met afwezigheidsmarkers als {"constructor": "waarde", "payload": …}. Een verwachting van de soort inconsistent vraagt een feit op het foutkanaal en mag de code van de foutsoort noemen (code, zie § 4).

Case files

A case*.json sits next to an ir.json and contains format, asOfDate, input and exactly one of expected and expectedFault. Numbers are exact lexemes in strings, never JSON floats; whatever the input omits is empty, and characteristics start false. A timeline is a list of segments with from (inclusive) and to (exclusive); a segment without from or without to has an open bound. An expected timeline is compared in the canonical form of RUNTIME-SEMANTICS chapter 3.1. An absence marker is written as {"constructor": "onbekend"}, a value of an attribute with absence markers as {"constructor": "waarde", "payload": …}. An expectation of kind inconsistent asks for a fact on the error channel and may name the code of the fault kind (code, see § 4).

Een rode case legt de foutsoort vast met haar code uit hoofdstuk 5.7b van RUNTIME-SEMANTICS en de parameters van die fout. In dit voorbeeld noemen de delen van een datumconstructie geen kalenderdag, want 31 april bestaat niet (EF-032):

A red case records the fault kind by its code from chapter 5.7b of RUNTIME-SEMANTICS and the parameters of that fault. In this example the parts of a date construction name no calendar day, since 31 April does not exist (EF-032):

De verifier en het negatieve corpus

De verifier in spec/verifier/ is geschreven in OCaml: een getypeerde AST, een strikte loader waarin onbekende of ontbrekende velden laadfouten zijn, en de WF-checks in checks.ml (meer dan 10.000 regels), uitputtend per knoopsoort, zodat een formaatuitbreiding zonder checks niet compileert. ref gebruikt dezelfde AST en loader. Uitvoer: verifier: PASS (exitcode 0) of per overtreding een regel WF-###.<slug> FAIL <pointer>: <message> (exitcode 1); een laadfout geeft exitcode 2. WF-### is de regel, de slug noemt de tak van die regel die afging, met één slug per berichtsjabloon, en samen vormen ze de sleutel. De pointer is een JSON-pointer in het document. verifier --arms geeft hetzelfde rapport voor een programma: per overtreding de sleutel, de pointer en de benoemde parameters die het bericht noemt, als JSON. verifier --dependency-edges drukt de afhankelijkheidsgraaf van hoofdstuk 5 af, die gate 15 naast de regelgraaf van de Drools-backend legt.

Negatieve documenten

Een map in corpus/negative/ heet wf###-slug; gate 3 leidt de regel af uit de mapnaam en eist dat de verifier het document om die regel afwijst. Een expect.txt in de map legt de tak vast: de eerste regel is een sleutel WF-###.<slug> van die regel, elke volgende regel een paar naam=waarde, en de verifier moet die sleutel melden met elk paar onder de parameters van één overtreding. De pin noemt een sleutel en parameters en geen berichttekst, dus een herformulering van een bericht breekt geen pin. Elke JSON-pointer die het rapport citeert, moet in het document bestaan. Het document moet laadbaar zijn, niet schema-geldig: de fout is semantisch. Een voorbeeld:

The verifier and the negative corpus

The verifier in spec/verifier/ is written in OCaml: a typed AST, a strict loader in which unknown or missing fields are load errors, and the WF checks in checks.ml (more than 10,000 lines), exhaustive per node kind, so a format extension without checks does not compile. ref uses the same AST and loader. Output: verifier: PASS (exit code 0) or, per violation, a line WF-###.<slug> FAIL <pointer>: <message> (exit code 1); a load error exits with code 2. WF-### is the rule, the slug names the arm of that rule that fired, one slug per message template, and together they form the key. The pointer is a JSON pointer into the document. verifier --arms gives the same report for a program: per violation the key, the pointer and the named parameters the message quotes, as JSON. verifier --dependency-edges prints the dependency graph of chapter 5, which gate 15 compares with the rule graph of the Drools backend.

Negative documents

A directory in corpus/negative/ is named wf###-slug; gate 3 derives the rule from the directory name and requires the verifier to reject the document for that rule. An expect.txt in the directory pins the arm: its first line is a key WF-###.<slug> of that rule, each further line a pair name=value, and the verifier must report that key with every pair among the parameters of one violation. The pin names a key and parameters, not message text, so rewording a message breaks no pin. Every JSON pointer the report cites must resolve in the document. The document must load but need not be schema-valid: the defect is semantic. An example:

Het golden-document jutterswet-penningjaar leest een kenmerk genegeerd, maar niet op een cyclus:

The golden document jutterswet-penningjaar reads a characteristic negated, but not on a cycle:

De negatieve case wf046-negated-read-in-recursive-cycle legt de negatie wel op een cyclus: een recursieve objectcreatie schrijft leeftijd, een kenmerkregel leidt daaruit volwassen af, en de creatie leest volwassen genegeerd. Dan bestaan er geen strata:

The negative case wf046-negated-read-in-recursive-cycle puts the negation on a cycle: a recursive object creation writes leeftijd, a characteristic rule derives volwassen from it, and the creation reads volwassen negated. Then no strata exist:

Dit document heeft geen expect.txt; een ander document voor dezelfde regel wel:

This document has no expect.txt; another document for the same rule has one:

Runtime-semantiek en de referentie-interpreter

spec/RUNTIME-SEMANTICS.md legt in elf hoofdstukken vast wat een IR-document betekent, met vergelijkingen, tabellen en uitgewerkte voorbeelden die letterlijk tests van ref/ worden. De kernbeslissingen:

leegte

Leeg is "the distinguished absence of a value, belonging to no datatype", dus geen nul en geen onwaar; FEEL-achtige null-propagatie is een non-goal. Een schrijver die leeg oplevert, beslist niets. De afwezigheidsmarkers onbekend en niet van toepassing zijn gevulde waarden van een sum type (hoofdstuk 9.5).

rekenkunde

Exact en rationeel: een getal is een breuk t/n in laagste termen, dus 1/3 × 3 = 1.

tijdlijnen

"a function from days to values that is constant on each of finitely many periods", over alle tijd: een dag zonder segment is leeg. Een operator of voorwaarde zonder eigen tijdsemantiek leest een tijdlijn per dag; voor leegte gelden een period-coalescing en een contributor-skipping rule.

verdeling

"recurrence equations over recipient groups": één gesloten definitie voor alle drie de methoden.

fixpoint

"A rule set does not run; it holds": de betekenis is het kleinste fixpoint van de vergelijkingen. Ook geschreven waarden, fouten en deponeringen op het foutkanaal tellen zoals ze aan het fixpoint staan (hoofdstuk 5.7).

negatie

Een genegeerde lezing van een afgeleid kenmerk ziet het fixpoint van het positieve deel; geketende negatie krijgt een stratum per schakel.

effective type

Een type-annotatie op de wire is een afleiding uit de operanden; een verwijzing heeft er geen, omdat de declaratie de enige bron is. De spec zegt over kopie en afleiding: "Neither is a source"; gate 13 dwingt dat af.

Een uitgewerkt voorbeeld

Sectie 4.6 geeft een verdeling met absolute waarden:

Runtime semantics and the reference interpreter

spec/RUNTIME-SEMANTICS.md fixes in eleven chapters what an IR document means, with equations, tables and worked examples that become tests of ref/ verbatim. The core decisions:

emptiness

Empty is "the distinguished absence of a value, belonging to no datatype", so neither zero nor false; FEEL-style null propagation is a non-goal. A writer that yields empty decides nothing. The absence markers onbekend and niet van toepassing are filled values of a sum type (chapter 9.5).

arithmetic

Exact and rational: a number is a fraction t/n in lowest terms, so 1/3 × 3 = 1.

timelines

"a function from days to values that is constant on each of finitely many periods", over all time: a day without a segment reads empty. An operator or condition without a time semantics of its own reads a timeline per day; for emptiness a period-coalescing and a contributor-skipping rule hold.

allocation

"recurrence equations over recipient groups": one closed definition for all three methods.

fixpoint

"A rule set does not run; it holds": the meaning is the least fixpoint of the equations. Written values, faults and deposits on the error channel, too, count as they stand at the fixpoint (chapter 5.7).

negation

A negated reading of a derived characteristic sees the fixpoint of the positive part; chained negation gets one stratum per link.

effective type

A type annotation on the wire is a derivation over the operands; a reference has none, because the declaration is the one source. The spec says of copy and derivation: "Neither is a source"; gate 13 enforces this.

A worked example

Section 4.6 gives an allocation with absolute values:

In ref/test/test_ref.ml staat hetzelfde voorbeeld:

The same example in ref/test/test_ref.ml:

De suite (dune build @ref/runtest) meldt test_ref: all N worked examples pass, met N boven de duizend; gate 5 bewaakt een ondergrens voor dat getal.

De referentie-interpreter

ref/ is een "small, slow, readable tree-walker" naar het model van WebAssembly: exacte breuken, en buiten de geïmplementeerde deelverzameling altijd een fout met positie. --noop slaat de evaluatie over, zodat gate 7 kan eisen dat golden cases dan falen; --trace schrijft voor elke vorm met een voorwaarde de lezing van die voorwaarde in het fixpunt (RUNTIME-SEMANTICS hoofdstuk 5.12), die gate 17 naast de lezingen van de Drools-backend legt. Bij een rode case meldt de runner elke waargenomen foutsoort als CODE-regel en de vastgelegde als CODE-PINNED-regel; gate 8 leest die (zie § 7).

The suite (dune build @ref/runtest) reports test_ref: all N worked examples pass, with N above a thousand; gate 5 enforces a lower bound on that number.

The reference interpreter

ref/ is a "small, slow, readable tree-walker" on the WebAssembly model: exact fractions, and outside the implemented subset always a fault with its position. --noop skips evaluation, so that gate 7 can require golden cases to fail; --trace writes, for every form with a condition, the reading of that condition at the fixpoint (RUNTIME-SEMANTICS chapter 5.12), which gate 17 compares with the readings of the Drools backend. For a red case the runner reports every observed fault kind as a CODE line and the pinned one as a CODE-PINNED line; gate 8 reads those (see § 7).

ref/ en spec/verifier/ delen geen code met de productieruntime van de Drools-backend (backends/drools, pakket dev.uchar.regelspraak.runtime); gate 1 zoekt in beide naar vijf tokens:

ref/ and spec/verifier/ share no code with the production runtime of the Drools backend (backends/drools, package dev.uchar.regelspraak.runtime); gate 1 searches both for five tokens:

De Drools-backend

De Drools-backend leest het IR van de wire, zoals ref en Clingo. Eén analyse (TmsTranspiler) maakt per regel een plan, en twee weergaven bouwen daaruit een regelbasis: het executable model van Drools (PatternDslRendering), de tak die gate 12 met ref en Clingo vergelijkt en waarmee de distributie bouwt, en DRL-tekst (DrlRendering), waarin elke RegelSpraak-toets en -berekening een Java-functie is met de RegelSpraak-zin erboven. Beide takken leiden af met truth maintenance: een afgeleid feit wordt logisch ingevoegd en rust op de waarden die de regel las, en Drools trekt het in zodra een van die waarden verandert. Tijdens het vuren schrijft de backend dus geen objecten, en hij heeft geen no-loop en geen salience nodig. Gate 12 eist dat de DRL-tekst per golden dezelfde statusregel geeft als het executable model, en gates 13 en 17 draaien beide takken. De routes van een regel naar Drools staan in § 6.

The Drools backend

The Drools backend reads the IR off the wire, as ref and Clingo do. One analysis (TmsTranspiler) makes a plan per rule, and two renderings build a rule base from it: Drools' executable model (PatternDslRendering), the branch that gate 12 compares with ref and Clingo and that the distribution builds with, and DRL text (DrlRendering), in which every RegelSpraak test and calculation is a Java function with the RegelSpraak sentence above it. Both branches derive with truth maintenance: a derived fact is inserted logically and rests on the values the rule read, and Drools withdraws it as soon as one of those values changes. While it fires, the backend therefore writes no objects, and it needs no no-loop and no salience. Gate 12 requires the DRL text to give the same status line per golden as the executable model, and gates 13 and 17 run both branches. The routes from a rule to Drools are in § 6.

De lezing van een voorwaarde

De lezing van de voorwaarde van een vorm op een object is de evaluatie van die voorwaarde op het fixpoint, de eindtoestand van de sessie, vastgelegd per knoop (RUNTIME-SEMANTICS hoofdstuk 5.12). Een lezing schrijft niets en verandert geen uitkomst. Een uitleg die zegt waarom een kenmerk geldt of waarom een waarde leeg bleef, leest de lezing, in plaats van de voorwaarde opnieuw uit te rekenen met een eigen semantiek. Elk paar van vorm en object heeft één status: HOLDS, FAILS, FAULTS, DISPLACED (onder meer een default die niet aan de beurt was, omdat een hogere default van zijn keten besliste) of OUTSIDE_VALIDITY. Elke knoop heeft een van vier uitkomsten: niet bereikt, een oordeel, een waarde met haar eenheid, of een fout met de EF-code van haar soort. Een knoop die de evaluatie als tijdlijn leest, heeft die tijdlijn als waarde. De knopen van een voorwaarde die per periode gelezen wordt, hebben het deel van de tijd waarin ze gelden.

runner --trace drukt de lezingen van een golden case af in de canonieke tekst van dat hoofdstuk, elke regel na reading: per lezing <vorm> <object> <status> en per knoop <vorm> <object> <nummer> <soort> <gevonden>. De vorm is de JSON-pointer van de regelversie, het object het label uit de case, en de knopen zijn genummerd in preorder, de voorwaarde eerst. Voor de regel "Een Jutter is penninggerechtigd indien zijn totaal aangemelde vondsten groter of gelijk is aan de vondstdrempel" van jutterswet-penningjaar:

The reading of a condition

The reading of a form's condition on an object is the evaluation of that condition at the fixpoint, the final state of the session, recorded node by node (RUNTIME-SEMANTICS chapter 5.12). A reading writes nothing and changes no outcome. An explanation that says why a characteristic holds or why a value stayed empty reads the reading, instead of evaluating the condition again in a semantics of its own. Every pair of form and object has one status: HOLDS, FAILS, FAULTS, DISPLACED (among others a default that was not at its turn, because a higher default of its chain decided) or OUTSIDE_VALIDITY. Every node has one of four outcomes: not reached, a verdict, a value with its unit, or a fault with the EF code of its kind. A node that the evaluation reads as a timeline has that timeline as its value. The nodes of a condition read per period have the part of all time in which they hold.

runner --trace prints the readings of a golden case in the canonical text of that chapter, each line after reading: per reading <form> <object> <status> and per node <form> <object> <number> <kind> <found>. The form is the JSON pointer of the rule version, the object the label from the case, and the nodes are numbered in pre-order, the condition first. For the rule "Een Jutter is penninggerechtigd indien zijn totaal aangemelde vondsten groter of gelijk is aan de vondstdrempel" (a Jutter is entitled to the penning if his total of reported finds is at least the find threshold) of jutterswet-penningjaar:

De Drools-backend maakt op verzoek een build met lezingen: naast de regel van elke vorm met een voorwaarde staat dan een leesregel, en DroolsBackendMain --readings drukt de lezingen af in dezelfde tekst. Gate 17 legt per casusbestand van elke golden de trace van ref naast de lezingen van beide Drools-takken en eist dat ze regel voor regel gelijk zijn; alleen mag de backend bij een lid van een kwantorfold unordered schrijven waar hij geen volgorde bijhoudt. De twee uitvoerders delen geen code (gate 1). Clingo levert geen lezingen.

Foutsoorten en meldingscodes

Hoofdstuk 5.7b van RUNTIME-SEMANTICS geeft elke foutsoort een code EF-###, met haar kanaal, de parameters die het voorval aanwijzen, de clausule die haar definieert en een getuige in het corpus. Er zijn vier kanalen: de case wordt bij het inlezen geweigerd (case input), de sessie breekt af (fault), elke uitvoerder weigert met naam een vorm waaraan de specificatie geen betekenis geeft (declined), of de sessie zet een feit op het foutkanaal en loopt door (§9.5). Een code wordt nooit hergebruikt of hernummerd. Een uitvoerder meldt de code naast de tekst van zijn melding, niet erin; de tekst verschilt per uitvoerder, de code niet. Daarom legt een rode case een code met parameters vast (§ 2), en vergelijkt gate 8 codes en geen tekst.

Elk onderdeel heeft daarnaast een codeschema voor zijn eigen meldingen: WF-###.<slug> voor de verifier (§ 3), RGS-### voor de RegelSpraak-frontend, DROOLS-### voor de vormen die de Drools-backend weigert, en REF-### en CLINGO-### voor de eigen weigeringen en grenzen van ref en Clingo. De laatste vier hebben elk één register: diagnostic-codes.tsv, DroolsCode.java, ref/codes.tsv en backends/clingo/codes.tsv. Gates 8, 10 en 12 houden elk register in beide richtingen gelijk aan de broncode: elke code die de broncode gebruikt, staat in het register, en elke code in het register komt in de broncode voor, op vervallen codes na. De frontend en de Drools-backend halen de tekst van een melding uit een catalogus per taal, Nederlands en Engels; de frontend schrijft standaard Nederlands, de Drools-backend Engels. Ref, verifier en Clingo schrijven alleen Engels.

On request the Drools backend makes a build with readings: beside the rule of every form with a condition there is then a reading rule, and DroolsBackendMain --readings prints the readings in the same text. Gate 17 compares, per case file of every golden, the trace of ref with the readings of both Drools branches and requires them to be equal line by line; the one allowance is that the backend may write unordered for a member of a quantifier fold where it keeps no order. The two executors share no code (gate 1). Clingo gives no readings.

Fault kinds and message codes

Chapter 5.7b of RUNTIME-SEMANTICS gives every fault kind a code EF-###, with its channel, the parameters that identify the occurrence, the clause that defines it and a witness in the corpus. There are four channels: the case is refused while it is read (case input), the session aborts (fault), every executor refuses by name a form to which the specification gives no meaning (declined), or the session puts a fact on the error channel and continues (§9.5). A code is never reused or renumbered. An executor reports the code beside the text of its message, not inside it; the text differs between executors, the code does not. That is why a red case pins a code with parameters (§ 2), and why gate 8 compares codes and not text.

Each component also has a code scheme for its own messages: WF-###.<slug> for the verifier (§ 3), RGS-### for the RegelSpraak frontend, DROOLS-### for the forms the Drools backend refuses, and REF-### and CLINGO-### for the own refusals and limits of ref and Clingo. The last four each have one register: diagnostic-codes.tsv, DroolsCode.java, ref/codes.tsv and backends/clingo/codes.tsv. Gates 8, 10 and 12 hold each register to the source code in both directions: every code the source uses is in the register, and every code in the register occurs in the source, retired codes excepted. The frontend and the Drools backend take the text of a message from a catalogue per language, Dutch and English; the frontend writes Dutch by default, the Drools backend English. Ref, the verifier and Clingo write English only.

De zeventien gates

Een gate is een script in scripts/ dat een eigenschap van de hele repository controleert. De hele set draait lokaal met make gates vóór elke landing (§ 8), en een rode gate houdt de landing tegen. .github/workflows/gates.yml legt de volgorde en de omgeving per gate vast, maar draait alleen als iemand hem met de hand start.

Elke gate waarvan een telling ongemerkt kan krimpen, draagt in zijn script een ondergrens EXPECTED_MIN_<naam>, met reden en meetdatum, en faalt met het gemeten getal en de ondergrens; een gate zonder ondergrens zegt in zijn script waarom. De waarden staan in de scripts en in de gatelijst van CLAUDE.md. Gate 9 vraagt een lokale catala-installatie; zonder catala faalt het script, dus het draait op een machine die catala heeft.

Regels voor de gate-set

De regels staan in README.md en CLAUDE.md:

The seventeen gates

A gate is a script in scripts/ that checks a property of the whole repository. The full set runs locally with make gates before every landing (§ 8), and a red gate blocks the landing. .github/workflows/gates.yml records the order and the environment per gate, but runs only when someone starts it by hand.

Every gate whose count could shrink unseen carries a floor EXPECTED_MIN_<name> in its script, with its reason and measurement date, and fails naming the measured number and the floor; a gate without a floor says in its script why. The values are in the scripts and in the gate list of CLAUDE.md. Gate 9 needs a local catala installation; without catala the script fails, so it runs on a machine that has catala.

Rules for the gate set

The rules are in README.md and CLAUDE.md:

• Een lege zone laat een gate falen; bij gate 2 doet zijn ondergrens dat, bij gate 4 doen de ondergrenzen van gates 5 en 8 het.
• Lijsten op naam, met reden, in gates 6, 7, 8, 10, 11, 12, 13, 15 en 17 falen zodra een vermelding verouderd is of naar een verdwenen case wijst.

Een ondergrens in een script, met haar meetdatum. De zone bevat meer documenten; de ondergrens vangt krimp, geen groei:

• An empty zone makes a gate fail; for gate 2 its floor does this, for gate 4 the floors of gates 5 and 8.
• Lists by name, with reasons, in gates 6, 7, 8, 10, 11, 12, 13, 15 and 17 fail as soon as an entry is out of date or points to a case that is gone.

A floor in a script, with its measurement date. The zone holds more documents; the floor catches shrinkage, not growth:

De routes van regels naar Drools

uchar vertaalt elke regel één keer en geeft die analyse aan Drools in twee vormen: als DRL-tekst, die Drools zelf parseert, en rechtstreeks als executable model via de PatternDSL-API, zonder gegenereerde Java-bron. Een frontend die LLVM-IR maakt, heeft dezelfde keuze: de IR als tekst schrijven (.ll) of haar met IRBuilder in het geheugen opbouwen. De backend gebruikt Drools 8.44.0.Final, de versie die backends/drools/pom.xml vastlegt.

The routes from rules to Drools

uchar translates every rule once and hands that analysis to Drools in two forms: as DRL text, which Drools parses itself, and directly as an executable model through the PatternDSL API, without generated Java source. A frontend that produces LLVM IR has the same choice: write the IR as text (.ll) or build it in memory with IRBuilder. The backend uses Drools 8.44.0.Final, the version backends/drools/pom.xml pins.

analyse

IrLoader laadt ir.json in een RegelSpraakModel. TmsTranspiler maakt daaruit per regel een plan (RulePlan): de linkerkant in volgorde (patronen, negaties, accumulates en toetsen) en de consequentie. Een afgeleid kenmerk of een afgeleide waarde voegt de consequentie logisch in, en alles wat de afleiding leest, staat als patroon in de linkerkant, zodat Drools haar intrekt als dat verandert. Beide weergaven nemen de plannen (samen het Modelplan) over zonder zelf iets te beslissen; wat de analyse weigert, weigeren beide takken met dezelfde zin.

feitklassen

FactModelGenerator schrijft per objecttype een Java-klasse (dev.uchar.regelspraak.facts), en BeanCompiler compileert die in het geheugen met javax.tools, één keer per inhoud per JVM. De analyse laadt de beanklassen uit de ClassLoader die dat oplevert, en de DRL-build krijgt hem met KieHelper.setClassLoader; beide takken werken dus met dezelfde klassen. Een relatie met twee meervoudige rollen heeft geen veld op een bean en staat, zoals een relatie die een vorm maakt, als RelationLink-feiten in de sessie.

DRL_TEXT

DrlRendering schrijft het Modelplan als DRL-tekst (TmsTranspiler.drl()): regels in het dialect MVEL, elke toets en berekening als Java-function met de RegelSpraak-zin als commentaar erboven. KieHelper geeft de tekst aan de DRL-pijplijn van Drools: DrlParser maakt er een PackageDescr van, en KnowledgeBuilderImpl bouwt daaruit RuleImpl-objecten met MVEL-voorwaarden (MVELConstraint) en compileert de functies. Een tekst die Drools weigert, is een fout van de weergave (IllegalStateException), geen weigering van een vorm.

EXEC_MODEL

PatternDslRendering roept per plan de PatternDSL aan (PatternDSL.rule(…).build(…), pattern(…).expr(…).bind(…)) en verzamelt de regels in een ModelImpl, een org.drools.model.Model; voorwaarden en berekeningen zijn lambda's die ClosureRendering uit het plan samenstelt. KieBaseBuilder.createKieBaseFromModel geeft het Model aan KiePackagesBuilder, die er RuleImpl-objecten met lambda-voorwaarden (LambdaConstraint) van maakt. De build schrijft voor de regels geen tekst en geen Java-bron.

RuleImpl, KieBase

Beide takken eindigen in RuleImpl-objecten in een InternalKnowledgePackage (drools-base). De KieBase zet elke RuleImpl met ReteooBuilder.addRule om in knopen van het netwerk (org.drools.core.reteoo), en een KieSession evalueert dat netwerk met de klassen in org.drools.core.phreak (RuleNetworkEvaluator, PhreakJoinNode, …).

codegen van Drools

Drools kan ook zelf van DRL een executable model maken: ModelGenerator schrijft uit een PackageDescr Java-bron met PatternDSL-aanroepen, die bij de Maven-build van het project wordt gecompileerd, of tijdens het draaien met KieBuilder.buildAll(ExecutableModelProject.class). uchar gebruikt die codegen niet.

afnemers

Na de build behandelt DroolsBackend beide takken gelijk: dezelfde regels onder dezelfde namen, dezelfde feiten en dezelfde driver (insert, fire, fixpointOf, setDerivedValues). De beslisservice van regelspraak-toolchain (image decision-service) bouwt op EXEC_MODEL; bin/regelspraak drl en de playground van de dienst tonen de tekst van DRL_TEXT. Gates 12, 13 en 17 spelen het corpus af op beide takken, en gate 12 eist per golden dezelfde statusregel (gates).

analysis

IrLoader loads ir.json into a RegelSpraakModel. TmsTranspiler makes a plan of it per rule (RulePlan): the left-hand side in order (patterns, negations, accumulates and tests) and the consequence. The consequence inserts a derived characteristic or a derived value logically, and everything the derivation reads is a pattern in the left-hand side, so Drools retracts the derivation when that changes. Both renderings take over the plans (together the Modelplan) without deciding anything themselves; what the analysis refuses, both branches refuse in the same sentence.

fact classes

FactModelGenerator writes a Java class per object type (dev.uchar.regelspraak.facts), and BeanCompiler compiles them in memory with javax.tools, once per content per JVM. The analysis loads the bean classes from the resulting ClassLoader, and the DRL build gets it through KieHelper.setClassLoader; both branches therefore work with the same classes. A relation with two to-many roles has no field on a bean and stands, like a relation a form creates, in the session as RelationLink facts.

DRL_TEXT

DrlRendering writes the Modelplan as DRL text (TmsTranspiler.drl()): rules in the MVEL dialect, every test and computation as a Java function with the RegelSpraak sentence as a comment above it. KieHelper hands the text to Drools' DRL pipeline: DrlParser turns it into a PackageDescr, and KnowledgeBuilderImpl builds RuleImpl objects with MVEL constraints (MVELConstraint) from it and compiles the functions. A text that Drools rejects is a fault of the rendering (IllegalStateException), not a refusal of a form.

EXEC_MODEL

PatternDslRendering calls the PatternDSL per plan (PatternDSL.rule(…).build(…), pattern(…).expr(…).bind(…)) and collects the rules in a ModelImpl, an org.drools.model.Model; constraints and computations are lambdas that ClosureRendering assembles from the plan. KieBaseBuilder.createKieBaseFromModel hands the Model to KiePackagesBuilder, which makes RuleImpl objects with lambda constraints (LambdaConstraint) of it. The build writes no text and no Java source for the rules.

RuleImpl, KieBase

Both branches end in RuleImpl objects in an InternalKnowledgePackage (drools-base). The KieBase turns every RuleImpl into nodes of the network with ReteooBuilder.addRule (org.drools.core.reteoo), and a KieSession evaluates that network with the classes in org.drools.core.phreak (RuleNetworkEvaluator, PhreakJoinNode, …).

Drools' codegen

Drools can also make an executable model from DRL itself: ModelGenerator writes Java source with PatternDSL calls from a PackageDescr, compiled in the project's Maven build or at run time with KieBuilder.buildAll(ExecutableModelProject.class). uchar does not use that codegen.

consumers

After the build, DroolsBackend treats both branches alike: the same rules under the same names, the same facts and the same driver (insert, fire, fixpointOf, setDerivedValues). The decision service of regelspraak-toolchain (image decision-service) builds on EXEC_MODEL; bin/regelspraak drl and the service's playground show the text of DRL_TEXT. Gates 12, 13 and 17 replay the corpus on both branches, and gate 12 demands the same status line per golden (gates).

De corpuszones

Het corpus is het uitvoerbare testmateriaal van de specificatie (herkomst: zie het overzicht). Stand op 7 november 2026:

Golden en anker samen: 407 ir.json en 1135 casusbestanden.

Anker, rood en toelating

The corpus zones

The corpus is the specification's executable test material (provenance: see the overview). Figures as of 7 November 2026:

Golden and anchor together: 407 ir.json files and 1135 case files.

Anchor, red cases and admission

Een rode case moet waarneembaar falen, bij het laden of in de evaluatie, met de vastgelegde code en parameters: in ref, in Clingo en in Drools. Dat geldt ook voor WF-044 (Unresolved, foutsoort EF-019). Uitzonderingen staan met reden op de lijsten van gate 8: een case waarvan Drools de vorm niet draagt, met de code van zijn weigering, en een case waarop ref of Clingo om een eigen reden faalt, met die code. Een fout die alleen de vangnetcode van een uitvoerder draagt, de code van de laatste tak van een dispatch, telt als een andere code dan de vastgelegde. Golden bevat alleen expected, red alleen expectedFault.

Wie een case met de hand schrijft, rekent de verwachte waarden eerst zelf uit; ref bevestigt ze daarna. Gesynthetiseerde cases (golden/synth*, 33 mappen) komen alleen binnen via scripts/admit.sh, volgens CLAUDE.md "only when the full differential square agrees", dus alleen als ref, Clingo en Drools op dezelfde uitkomst uitkomen; elk verschil gaat naar adversariële triage, "never a case to admit".

A red case must fail observably, at load or in evaluation, with the pinned code and parameters: in ref, in Clingo and in Drools. This holds for WF-044 too (Unresolved, fault kind EF-019). Exceptions are listed with a reason on the lists of gate 8: a case whose form Drools does not carry, with the code of its refusal, and a case on which ref or Clingo fails for a reason of its own, with that code. A fault that carries only an executor's fallback code, the code of the last arm of a dispatch, counts as a code other than the pinned one. Golden contains only expected, red only expectedFault.

Whoever writes a case by hand computes its expected values first; ref then confirms them. Synthesized cases (golden/synth*, 33 directories) enter only through scripts/admit.sh, in the words of CLAUDE.md "only when the full differential square agrees", that is, only when ref, Clingo and Drools reach the same outcome; any disagreement goes to adversarial triage, "never a case to admit".

Lokaal draaien

De scripts vragen een git-checkout; de overige eisen hangen per gate af (versies alleen waar vastgelegd):

OCaml

OCaml 5 met opam en dune: opam install dune yojson zarith

Python 3

voor een groot deel van de gates; gates 2 en 4 vragen daarbij jsonschema of uv

clingo

op Ubuntu uit het pakket gringo

catala

alleen voor gate 9

JDK

21 of hoger, voor gates 10 tot en met 13 en 15 tot en met 17, en voor het Drools-been van gate 8, dat zonder Java met een melding wordt overgeslagen

ANTLR, JUnit

antlr-4.13.2-complete.jar en junit-platform-console-standalone-1.10.2.jar, die de Makefile van de frontend in frontends/regelspraak/lib/ zet

Maven

voor de Drools-backend (Drools 8.44.0.Final). Gates 8, 11, 12, 13, 15 en 17 nemen de jar zoals hij is wanneer hij nieuwer is dan elke bron, en bouwen hem anders opnieuw, offline (mvn -o); de eerste keer is daarom één online mvn -B -f backends/drools/pom.xml package nodig

make

GNU make 3.81 of nieuwer, voor make gates

De hele set draait met één commando in de root van de repository:

Running it locally

The scripts need a git checkout; the other requirements vary per gate (versions only where pinned):

OCaml

OCaml 5 with opam and dune: opam install dune yojson zarith

Python 3

for many of the gates; gates 2 and 4 also need jsonschema or uv

clingo

on Ubuntu from the gringo package

catala

only for gate 9

JDK

21 or later, for gates 10 to 13 and 15 to 17, and for the Drools leg of gate 8, which is skipped with a message when Java is missing

ANTLR, JUnit

antlr-4.13.2-complete.jar and junit-platform-console-standalone-1.10.2.jar, which the frontend's Makefile places in frontends/regelspraak/lib/

Maven

for the Drools backend (Drools 8.44.0.Final). Gates 8, 11, 12, 13, 15 and 17 take the jar as it is when it is newer than every source, and rebuild it otherwise, offline (mvn -o); the first time therefore needs one online mvn -B -f backends/drools/pom.xml package

make

GNU make 3.81 or later, for make gates

The full set runs with one command in the root of the repository:

make gates controleert eerst of de gate-scripts van het Makefile dezelfde zijn als die van .github/workflows/gates.yml, in dezelfde volgorde, en als die van de gatelijst in CLAUDE.md; wijken ze af, dan stopt het voordat er iets gebouwd is. Daarna bouwt het naast elkaar de drie bomen die de gates lezen: de OCaml-werkruimte, de RegelSpraak-frontend en de jar van de Drools-backend, elk alleen als een bron nieuwer is dan het product. Dan draait het de zeventien gates parallel in dezelfde checkout, zoveel tegelijk als de machine cores heeft, met een log per gate onder out/gates/<run>/ en een summary.txt met een regel per gate, in de volgorde van gates.yml. De stap after-run draait de drie bouwstappen daarna opnieuw; elk moet vers zijn, anders veranderde er tijdens de run een bron of bouwde een gate zelf. Een rode bouwstap, een rode gate, een rode after-run of een ontbrekende regel geeft een exitcode ongelijk aan nul. Op 25 oktober 2026 duurde de hele set 283 seconden, op een machine met 16 cores; gate 12 duurt het langst, omdat het de JUnit-suite van de Drools-backend draait (Result van de kaart parallel-gate-replays).

Een enkele gate draait met zijn eigen script, in de omgeving die het Makefile hem geeft:

make gates first checks that the gate scripts of the Makefile are those of .github/workflows/gates.yml, in the same order, and those of the gate list in CLAUDE.md; if they differ, it stops before anything is built. Then it builds, side by side, the three trees the gates read: the OCaml workspace, the RegelSpraak frontend and the Drools backend jar, each only when a source is newer than the product. Then it runs the seventeen gates in parallel in the same checkout, as many at once as the machine has cores, with one log per gate under out/gates/<run>/ and a summary.txt with one line per gate, in the order of gates.yml. The step after-run then runs the three builds again; each must be fresh, otherwise a source changed or a gate built during the run. A red build, a red gate, a red after-run or a missing line gives a non-zero exit code. On 25 October 2026 the full set took 283 seconds on a machine with 16 cores; gate 12 takes longest, because it runs the JUnit suite of the Drools backend (Result of the card parallel-gate-replays).

A single gate runs with its own script, in the environment the Makefile gives it:

Verifier en ref afzonderlijk:

The verifier and ref on their own:

Gates 2, 3 en 5 nemen ook losse bestanden; gates 6 en 12 nemen geen argumenten. WAY-OF-WORKING.md schrijft gate 1 voor vóór elke commit en make gates vóór elke landing.

Gates 2, 3 and 5 also take individual files; gates 6 and 12 take no arguments. WAY-OF-WORKING.md prescribes gate 1 before every commit and make gates before every landing.

Bijdragen

Stateloze agent-sessies bouwen uchar (zie herkomst). Een sessie onthoudt niets; daarom is de repository de toestand. Het plan zegt waarom de controles mechanisch zijn:

Contributing

Stateless agent sessions build uchar (see provenance). A session remembers nothing; that is why the repository is the state. The plan explains why the checks are mechanical:

Kaarten

Werk loopt via kaarten, werkbeschrijvingen met vooraf vastgelegde acceptatiecriteria, in backlog/new/, doing/ en done/. De maintainer plant en wijst elke sessie haar werk toe. Het formaat:

Cards

Work runs through cards, work descriptions with acceptance criteria stated up front, in backlog/new/, doing/ and done/. The maintainer schedules and assigns each session its work. The format:

Een kaart gaat in de eerste commit naar doing/ en bij de merge naar done/, met een Result:-noot: wat landde, wat bewust bleef liggen, en voorgestelde tekst voor PLAN.md of CONSTRUCTS.md, die alleen de hoofdsessie verwerkt, de eigen sessie van de maintainer op main.

Eén sessie, één kaart, één branch

Elke kaart krijgt een branch card/<slug> in een eigen worktree en gaat fast-forward-only naar main. Parallel werk mag alleen bij onderzoek, review of kaarten waarvan de lijsten met te wijzigen bestanden ("May touch") elkaar niet overlappen; een mergeconflict betekent dat de kaarten verkeerd zijn afgebakend. Bij rode gates aan de start stopt de sessie.

A card moves to doing/ in the first commit and to done/ on merge, with a Result: note: what landed, what was deliberately left, and proposed text for PLAN.md or CONSTRUCTS.md, which only the main session, the maintainer's own session on main, applies.

One session, one card, one branch

Every card gets a branch card/<slug> in its own worktree and goes to main fast-forward only. Parallel work is allowed only for research, review or cards whose lists of files they may change ("May touch") do not overlap; a merge conflict means the cards were scoped wrongly. If the gates are red at the start, the session stops.

Beschermde paden

Beschermde paden mag een sessie alleen voorstellen; de maintainer merget. CLAUDE.md beschermt binnen spec/ de twee bindende documenten, schema/ en verifier/; CODEOWNERS claimt met opzet heel spec/. GitHub dwingt die claim alleen af als een regel op main review door code owners eist. Een ruleset op main blokkeert force-pushes en het verwijderen van de branch, maar eist geen pull request en dus geen review. De review verloopt volgens het mandaat- en reviewprotocol van WAY-OF-WORKING.md.

Protected paths

A session may only propose changes to protected paths; the maintainer merges. Within spec/, CLAUDE.md protects the two normative documents, schema/ and verifier/; CODEOWNERS deliberately claims all of spec/. GitHub enforces that claim only when a rule on main requires review from code owners. A ruleset on main blocks force pushes and deletion of the branch, but it requires no pull request and therefore no review. Review follows the mandate-and-review protocol of WAY-OF-WORKING.md.

Namen

Elke identifier is Engels: klassen, methoden, velden, OCaml-modules en -constructors, ASP-predicaten, shellvariabelen, CLI-vlaggen en testnamen, en ook elke bestands- en mapnaam. Waar de wire een naam voor een begrip heeft, gebruikt de code die naam, anders de term uit de Engelse spec. Nederlands blijft wat als Nederlands geschreven is: domeininhoud (de Jutterswet, gedeclareerde namen, RegelSpraak-bronnen, caselabels en de golden-namen jutterswet-*, synth* en ww-*), de sleutelwoorden van RegelSpraak, de regels van de ANTLR-grammatica, enumeratiewaarden in v0-spelling die op de wire of in een melding komen, de namen die de productieruntime bij naam leest, de variabelen in de DRL-tekst die de Drools-backend maakt, en de 47 TOKA-fragmenten. Kaarten, Result:-noten en commitberichten mogen Nederlands of Engels zijn; de identifiers die ze noemen, zijn Engels. De volledige afspraak staat onder "Conventions" in CLAUDE.md.

Spec-first

De distributie regelspraak-toolchain, opvolger van regelspraak-java, neemt uchar op als git-submodule en bouwt daaruit de RegelSpraak-frontend en de Drools-backend; de commit van de submodule is de pin. Een delta landt eerst in uchar (spec, corpus, schema); daarna verzet de distributie haar pin. Een pincontrole daar faalt als de submodule niet geïnitialiseerd is, niet op de vastgelegde commit staat of eigen wijzigingen heeft, als die commit niet op main van uchar staat, of als ANTLR, Drools, Jackson of JUnit een andere versie heeft dan in uchar.

Names

Every identifier is English: classes, methods, fields, OCaml modules and constructors, ASP predicates, shell variables, CLI flags and test names, and every file and directory name too. Where the wire has a name for a concept, the code uses that name, otherwise the term of the English spec. What was written in Dutch stays Dutch: domain content (the Jutterswet, declared names, RegelSpraak sources, case labels and the golden names jutterswet-*, synth* and ww-*), the keywords of RegelSpraak, the rules of the ANTLR grammar, enumeration values in v0 spelling that reach the wire or a message, the names the production runtime reads by name, the variables in the DRL text the Drools backend generates, and the 47 TOKA fragments. Cards, Result: notes and commit messages may be Dutch or English; the identifiers they name are English. The full convention is under "Conventions" in CLAUDE.md.

Spec first

The distribution regelspraak-toolchain, successor of regelspraak-java, includes uchar as a git submodule and builds its RegelSpraak frontend and Drools backend from it; the submodule's commit is the pin. A delta lands in uchar first (spec, corpus, schema); the distribution then moves its pin. A pin check there fails when the submodule is not initialised, not on the recorded commit or has changes of its own, when that commit is not on uchar's main, or when ANTLR, Drools, Jackson or JUnit differs in version from uchar.

Wat nog komt

Van het plan staat alleen fase 6 nog open: "Catala as a backend: opportunistic, possibly never". De specificatie markeert wat nog open is ter plekke met OPEN, en voor tijd in de tabel van RUNTIME-SEMANTICS hoofdstuk 3.12; de besluiten over het project als geheel houdt spec/PLAN.md bij in zijn § 9.

Een deel van de besluiten in die paragraaf is voorlopig: een sessie nam het tijdens het werk aan een kaart, en de maintainer kan het terugdraaien. PLAN § 9 noemt bij de meeste besluiten wat open blijft. Een greep, op 7 november 2026:

What comes next

Of the plan, only phase 6 is still open: "Catala as a backend: opportunistic, possibly never". The specification marks what is still open with OPEN where it occurs, and for time in the table of RUNTIME-SEMANTICS chapter 3.12; the decisions about the project as a whole are kept in § 9 of spec/PLAN.md.

Some of the decisions in that section are provisional: a session took them while working on a card, and the maintainer can reverse them. PLAN § 9 states for most decisions what remains open. A selection, on 7 November 2026:

instantiegeordende kring

Een waarde van een object mag dezelfde waarde van zijn voorganger in een keten lezen (IR-SPEC hoofdstuk 5.3). Een lezing over een relatie waarvan de rol aan de kant van het type van de kring meervoudig is, wordt geweigerd.

vormanker

Een knoop met het anker heeft in hoofdstuk 5.12 geen eigen lezing, en de RegelSpraak-frontend schrijft geen geankerde kwantorfold, hoewel het IR die vorm heeft.

kenmerk van een subtype

Een kenmerk dat op een subtype is gedeclareerd, mag op een object van het supertype getoetst worden; een attribuut van een subtype en een kenmerk dat twee zustertypen declareren nog niet.

Van de ontwerpvoorstellen en audits in spec/proposals/ noemt elk document in zijn statusregel wat het is: een voorstel, een aangenomen ontwerp of een audit. Eén ervan beschrijft werk dat buiten v1 valt:

instance-ordered cycle

A value of an object may read the same value of its predecessor in a chain (IR-SPEC chapter 5.3). A read over a relation whose role on the side of the cycle's type is to-many is refused.

form anchor

A node with the anchor has no reading of its own in chapter 5.12, and the RegelSpraak frontend writes no anchored quantifier fold, although the IR has that form.

characteristic of a subtype

A characteristic declared on a subtype may be tested on an object of the supertype; an attribute of a subtype and a characteristic that two sibling types declare may not yet.

Of the design proposals and audits in spec/proposals/, each document states in its status line what it is: a proposal, an adopted design or an audit. One of them describes work that lies outside v1:

Het lopende werk staat als kaarten in backlog/ (§ 9). Als optie vastgelegd is een verificatiebackend op SMT (smt-backend), die vragen over alle mogelijke casussen tegelijk beantwoordt. De schema's uchar-ir-v1.schema.json en uchar-case-v0.schema.json hebben elk een $id onder uchar.dev, en dat is een identificatie die (nog) niet resolveert.

Ongoing work is kept as cards in backlog/ (§ 9). On record as an option is a verification backend on SMT (smt-backend), which answers questions about all possible cases at once. The schemas uchar-ir-v1.schema.json and uchar-case-v0.schema.json each have an $id under uchar.dev, which is an identifier that does not resolve (yet).