docs: add RFC-020 date-aware reference resolution (as_of)

[tdjager]

Summary

RFC-020 — concept 2 of the temporal-validity split. Where RFC-019 (#766) adds a law end date relative to the global calculation_date, RFC-020 lets a reference be resolved at a different date and have that date propagate down its subtree.

Stacked on #766. Base branch is docs/rfc-019-temporal-validity so RFC-020's [RFC-019] links resolve in the docs link-check. The diff here is only rfc-020.md. When #766 merges, GitHub retargets this PR to main.

What it proposes

• as_of on a cross-law reference / open-term resolution. Default = dynamic (follows calculation_date, the hoofdregel). as_of: <date|$param> resolves the referenced law (and its subtree) at that date — modeling statische verwijzing, ex tunc, and eerbiedigende werking. Propagation: inherited down the subtree, innermost wins. The resolved date is recorded per reference in trace/receipt (RFC-013).
• Applicable date is computed by law, not engine heuristic: the Awb (heroverweging art. 7:11) and/or the specific law's overgangsrecht. The ex-nunc reading is jurisprudential (standard arrest ABRvS Greenpeace 28-10-2020, ECLI:NL:RVS:2020:2571; Steenwijkerland ECLI:NL:RVS:2016:3388; exception-side anchor Berg en Dal ECLI:NL:RVS:2018:610) and the overgangsrecht default is onmiddellijke werking (Aanwijzing 5.61) — so those defaults live in Engine Policy, overridable per reference.
• Multiple dates per beoordeling are codified: lex mitior (art. 5:46 lid 4 Awb; ABRvS 21-05-2025 ECLI:NL:RVS:2025:2223; ABRvS 30-08-2023 ECLI:NL:RVS:2023:3291; CBb 06-07-2021 ECLI:NL:CBB:2021:700) — proving as_of must be per-reference. With four faithfulness boundaries: mandatory & offender-favourable, punitive-only, only on gewijzigd inzicht van de wetgever, selector-in-law (MIN/IF, the engine never optimizes over dates).
• Three temporal axes named: instrument validity (RFC-019) vs substantive scope vs applicable-date selection.

Grounding

Every claim verified against the official sources: Awb art. 7:11 lid 1 and 5:46 lid 4 quoted verbatim (wetten.overheid.nl), Aanwijzingen 3.47 / 5.60 / 5.61 / 5.64 (BWBR0005730, status as drafting guidelines noted), and all six jurisprudence anchors pinned to their ECLIs on rechtspraak.nl. Worked YAML per mechanism (ex nunc/ex tunc, statische verwijzing, lex mitior) — all examples stay within the existing operation grammar; only as_of itself is new.

Review round processed

• Example C (lex mitior) rewritten to two inputs + MIN over variables (the earlier shape put source-objects inside operation values, which the schema does not allow).
• ECLIs added for all six anchors; CBb date corrected to 6 juli 2021; ABRvS 30-08-2023 disambiguated to ECLI:NL:RVS:2023:3291 (a same-day lex-certa ruling exists).
• Fourth lex-mitior boundary (gewijzigd inzicht van de wetgever, per ABRvS 21-05-2025).
• "zoals dat luidde op " attributed to the statutory formula (Wet IB 2001 art. 10bis.1), not to Aanwijzing 3.47's own wording.
• Example A marked illustrative (vreemdelingenwet_2000 has no verblijfsvergunning_verleend output yet; Awb 7:11 not yet in the corpus).
• Implementation notes: as_of in memoization/cycle-detection keys; source is additionalProperties: false so a new minor schema version is needed; selection failures reported relative to the resolved date.

Status

Draft — design discussion. Implementation follows once the open points (form of the Engine Policy default; reusable lex-mitior pattern) are settled, after RFC-019 lands.

[claude]

RFC-020: Date-Aware Reference Resolution (as_of)

This RFC is carefully grounded — every legal claim is tied to a verbatim statutory quote or pinned ECLI, the three temporal axes are cleanly separated, the lex-mitior boundaries faithfully track the gewijzigd-inzicht requirement (ABRvS 21-05-2025 is a notable recent anchor), and the design correctly rejects engine-level optimization in favour of a law-authored selector. The memoization cache key note (must include as_of to avoid Example C collision) and schema versioning implication are both caught and flagged. No critical or significant issues.

---

Minor

🟡 Example A: invalid YAML — duplicate input: key in a single code block (lines 134–147)

The ex-nunc and ex-tunc alternatives are shown in one fenced block with input: appearing twice at the top level. That is technically invalid YAML; a YAML parser would silently discard the first block or error, and readers trying to adapt the pattern get a misleading template. RFC-019's examples avoid this. These should be two separate fenced blocks with a brief label each.

# Alternative 1 — ex nunc (default): no as_of, uses calculation_date
input:
  - name: oorspronkelijk_recht
    source: { regulation: vreemdelingenwet_2000, output: verblijfsvergunning_verleend }

# Alternative 2 — ex tunc / eerbiedigende werking
input:
  - name: oorspronkelijk_recht
    source:
      regulation: vreemdelingenwet_2000
      output: verblijfsvergunning_verleend
      as_of: $besluit_datum

---

🟡 "Still open" is missing the calculation_date reset case

The propagation rule (§2) states "inherited down the subtree, innermost wins" with no mechanism to explicitly reset to calculation_date from within an inherited context. The only escape would be as_of: $calculation_date, but calculation_date is an engine-level value that is not currently accessible as a $-parameter in law YAML. If a referenced law is intended to always resolve its own sub-references at the current date (e.g., a dynamic rate table), there is presently no way to express that. This is likely intentional for temporal consistency, but the decision should be documented — either as an acknowledged constraint or as a third open point in the "Still open" section.

[claude]

.

[claude]

RFC-020: Date-Aware Reference Resolution (as_of)

This RFC is well-grounded and clearly structured. The three-axes separation (instrument validity / substantive scope / applicable-date selection) is the right framing, the legal citations are present and pinned to ECLIs, and the lex-mitior worked example is correctly expressed within the existing operation grammar. Two issues in the new text warrant attention before this lands.

---

🟠 Significant

1. Self-contradictory $calculation_date escape (Still open §, lines 200–205)

The RFC correctly states that calculation_date is not addressable as a $-parameter in law YAML. This is confirmed by the engine: Context stores it as a separate field distinct from the parameters: BTreeMap. But the same paragraph immediately proposes as_of: $calculation_date as "a schema addition":

calculation_date is an engine-level value that is not addressable as a $-parameter in law YAML … if a real corpus case needs it, an explicit escape (e.g. as_of: $calculation_date) would be a schema addition.

A schema addition alone cannot make $calculation_date resolve — the engine would also need to inject it into the parameters map, which has its own implications (reserved name collision; semantics in a nested-subtree context). As written this is misleading: it implies the escape is low-cost when it is not. Either say "no escape is currently possible — this is a deliberate constraint" (honest about the tradeoff already named), or explicitly flag it as requiring an engine change with the attendant design questions.

2. as_of propagation into IoC (open_terms/implements) not specified (§5, lines 109–113)

Section 5 addresses how as_of interacts with hooks and overrides, but the IoC pattern (RFC-003 open_terms/implements) is a third cross-law resolution path and is not mentioned. When law A references law B with as_of: $besluit_datum, and law B has open_terms filled by implementing regulation C, should C be selected at $besluit_datum (consistent with propagation semantics) or at calculation_date (current IoC behaviour)? Both answers are defensible but have different legal implications:

• Propagating into IoC: a statische verwijzing to an older version of B uses the implementing regulations that were in force on that date — legally correct but non-trivial to implement.
• Not propagating: the implementing regulation is always selected at calculation_date — simpler, but an undocumented exception to the "inherited down the subtree" rule.

This should be decided and stated explicitly, not left implicit.

---

🟡 Minor

3. Inconsistent YAML style in worked examples (lines 130, 178)

Example A (default case) and Example C use inline flow style (source: { regulation: wet_x, output: ..., as_of: ... }); the ex-tunc variant of Example A and Example B use block style. All four examples should use the same style; block style matches the existing corpus convention.

4. Missing test case: as_of past the target's own valid_to (Testing §, lines 213–214)

Test case 2 covers the success path: as_of before the target's valid_to resolves an old version even after calculation_date has moved past valid_to. The failure path is not tested: as_of: '2027-01-01' on a law with valid_to: '2026-12-31' should yield a SelectionReason error, not a silent miss. Implementation notes mention reporting selection failures relative to the resolved date, but a concrete test case should anchor this boundary.

[claude]

RFC-020 - Date-Aware Reference Resolution (as_of)

Scope: One new file, docs/src/content/rfcs/rfc-020.md (292 added lines, 0 deleted).

Summary

The RFC is carefully grounded. Every legal claim cites a statute, Aanwijzing, or pinned ECLI. The worked examples use valid schema grammar -- MIN is confirmed as a schema-level arithmeticOperation enum value and is implemented in packages/engine/src/operations.rs. The source.additionalProperties: false constraint and the need for a schema version bump are correctly identified. The core design decision (per-reference as_of, propagated down the subtree, innermost wins) correctly solves the problem RFC-019's single global date cannot.

---

Findings

Minor -- Test case 2 wording collides with test case 5

(Testing section, second bullet)

statische verwijzing: a fixed-date as_of keeps resolving an earlier version after the target's valid_to

Read in isolation, "after the target's valid_to" suggests the as_of date itself is past valid_to -- which is exactly test case 5 (error path). The intended meaning is that the current calculation_date is past valid_to while the frozen as_of is still within the validity window. Since the distinction between "as_of past valid_to -> error" and "calculation_date past valid_to, as_of within range -> success" is the central behaviour of the feature, the test description should be unambiguous.

Suggested rewording: "a fixed-date as_of resolves correctly when calculation_date is past the target's valid_to but as_of is within the validity window".

---

Minor -- RFC-013 missing from Depends on

**Depends on:** RFC-019 (Law End Dates), RFC-007 (Cross-Law Execution Model), RFC-008 (Awb Administrative Procedures)

Section 2 explicitly extends RFC-013's trace/receipt format: "the resolved date and selected version go into trace and receipt (RFC-013)". RFC-019, which extends the same receipt in the same way, consistently lists RFC-013 in its own Depends on. For implementer discoverability, RFC-013 should appear here too.

---

Minor -- Example C parameter provenance unannotated

as_of: $overtreding_datum
...
as_of: $beschikking_datum

Example A annotates $besluit_datum with "RFC-008 stage input; propagates through the referenced subtree". Example C uses two analogous stage inputs without an equivalent comment. Since overtreding_datum does not appear in RFC-008's existing bezwaartermijn example, a reader implementing the lex-mitior case will need to know where these parameters originate.

---

Not flagged

• Legal grounding -- all six ECLI anchors and statutory quotes (Awb art. 7:11 lid 1, art. 5:46 lid 4) correctly cited; Aanwijzingen 3.47/5.60/5.61/5.64 attribution accurate.
• IoC/implements propagation -- selecting implementing regulations at the propagated as_of date is legally correct and internally consistent with the subtree invariant.
• Memoization/cycle-detection key requirement -- correctly identified.
• "No reset to calculation_date" constraint -- explicitly flagged in Still Open with engine-change implications; adequate for draft stage.

[claude]

RFC-020 Review

Single file added: docs/src/content/rfcs/rfc-020.md. All findings are scoped to lines added in this diff.

---

Legal faithfulness

The legal grounding is solid. All cited articles are quoted correctly: Awb art. 5:46 lid 4 ("Artikel 1, tweede lid, van het Wetboek van Strafrecht is van overeenkomstige toepassing") is accurate; Aanwijzing 3.47 on statische/dynamische verwijzing and Aanwijzing 5.61 on onmiddellijke werking as the default are correctly characterised. The Greenpeace standard arrest (ECLI:NL:RVS:2020:2571) as the ex-nunc anchor and ABRvS 21-05-2025 (ECLI:NL:RVS:2025:2223) for the gewijzigd-inzicht boundary are appropriate; noting that Aanwijzingen are a besluit van de Minister-President (not substantive law) is the right calibration. The three-axis table (instrument validity / substantive scope / applicable-date selection) is a correct and useful clarification.

---

Minor issues

🟡 $beschikking_datum is not a defined RFC-008 stage input

Example C introduces $beschikking_datum and $overtreding_datum as $-parameters, citing them as "RFC-008 stage inputs, like $besluit_datum in Example A." RFC-008's lifecycle definitions use besluit_datum (at the BEHANDELING stage output), not beschikking_datum. A boete procedure would need its own lifecycle with overtreding_datum as a stage input — that lifecycle isn't yet modelled in RFC-008. Either use the established $besluit_datum naming or explicitly note that the boete lifecycle adds new stage inputs (and cross-reference where those will be defined).

---

🟡 Failure path testing: as_of before valid_from is missing

Test case 5 covers as_of past valid_to (law has ended). The symmetric case — as_of before valid_from (law hadn't entered force yet) — is equally likely in practice (e.g. resolving a rate table with an overtreding_datum predating the law). Add a sixth test case: as_of before the target law's valid_from should yield a SelectionReason error in the same way.

---

🟡 Unaddressed failure mode: as_of: $param when param is absent

§2 allows as_of: $param, but the "Still open" section and Implementation Notes are silent on the runtime case where the parameter is not supplied. Should the engine fall back to calculation_date (lenient) or treat it as a resolution error (strict)? Given the engine's zero-domain-knowledge policy (RFC-015), a silent fallback seems wrong — a missing required date is a caller error. Worth adding to the open items.

---

🟡 Typo: "corpus AWB" should be "corpus Awb"

In the Example A footnote: "Awb 7:11 is not yet in the corpus AWB" — all other occurrences in the document use "Awb". Trivial but inconsistent.

---

Schema claim verified

The source object in schema/v0.5.3/schema.json (line 571) does have "additionalProperties": false, confirming that adding as_of requires a new minor schema version as stated.

RFC cross-references verified

All referenced RFCs (001, 003, 007, 008, 013, 014, 015, 019) exist in docs/src/content/rfcs/. The /reference/glossary link resolves to docs/src/content/docs/reference/glossary.md. RFC-001 §8 ("Temporal Specifications") is the correct target.

[claude]

RFC-020 Review

Single file added: docs/src/content/rfcs/rfc-020.md. All findings are scoped to lines added in this diff.

---

Legal faithfulness

The legal grounding is solid. All cited articles are quoted correctly: Awb art. 5:46 lid 4 ("Artikel 1, tweede lid, van het Wetboek van Strafrecht is van overeenkomstige toepassing") is accurate; Aanwijzing 3.47 on statische/dynamische verwijzing and Aanwijzing 5.61 on onmiddellijke werking as the default are correctly characterised. The Greenpeace standard arrest (ECLI:NL:RVS:2020:2571) as the ex-nunc anchor and ABRvS 21-05-2025 (ECLI:NL:RVS:2025:2223) for the gewijzigd-inzicht boundary are appropriate. The three-axis table (instrument validity / substantive scope / applicable-date selection) is a correct and useful clarification.

---

Minor issues

🟡 $beschikking_datum is not a defined RFC-008 stage input

Example C introduces $beschikking_datum and $overtreding_datum as parameters, citing them as "RFC-008 stage inputs, like $besluit_datum in Example A." RFC-008's lifecycle definitions use besluit_datum (at the BEHANDELING stage output), not beschikking_datum. A boete procedure would need its own lifecycle with overtreding_datum as a stage input — that lifecycle is not yet modelled in RFC-008. Either use the established $besluit_datum naming or explicitly note that the boete lifecycle adds new stage inputs and cross-reference where those will be defined.

🟡 Failure path testing: as_of before valid_from is missing

Test case 5 covers as_of past valid_to (law has ended). The symmetric case — as_of before valid_from (law not yet in force) — is equally likely in practice (e.g. resolving a rate table with an overtreding_datum predating the law). Add a sixth test case: as_of before the target law's valid_from should yield a SelectionReason error in the same way.

🟡 Unaddressed failure mode: as_of: $param when param is absent

§2 allows as_of: $param, but the "Still open" section and Implementation Notes are silent on the runtime case where the parameter is not supplied. Should the engine fall back to calculation_date (lenient) or treat it as a resolution error (strict)? Given the zero-domain-knowledge policy (RFC-015), a silent fallback seems wrong — a missing required date is a caller error. Worth adding to the open items.

🟡 Typo: "corpus AWB" should be "corpus Awb"

In the Example A footnote: "Awb 7:11 is not yet in the corpus AWB" — all other occurrences in the document use "Awb".

---

Verified

• source in schema/v0.5.3/schema.json has "additionalProperties": false — the schema version bump claim is correct.
• All referenced RFCs (001, 003, 007, 008, 013, 014, 015, 019) exist. /reference/glossary resolves. RFC-001 §8 ("Temporal Specifications") is the correct target for the three-axes table citation.

[claude]

RFC-020 Review

Single file added: `docs/src/content/rfcs/rfc-020.md`. All findings are scoped to lines added in this diff.

---

Legal faithfulness

The legal grounding is solid. Awb art. 5:46 lid 4 is quoted correctly; Aanwijzing 3.47 on statische/dynamische verwijzing and Aanwijzing 5.61 on onmiddellijke werking as the default are correctly characterised. The Greenpeace standard arrest (ECLI:NL:RVS:2020:2571) as the ex-nunc anchor and ABRvS 21-05-2025 (ECLI:NL:RVS:2025:2223) for the gewijzigd-inzicht boundary are appropriate. The three-axis table (instrument validity / substantive scope / applicable-date selection) is a correct and useful distinction.

---

🟡 Minor: `$beschikking_datum` is not a defined RFC-008 stage input

Example C introduces `$beschikking_datum` and `$overtreding_datum`, citing them as "RFC-008 stage inputs, like `$besluit_datum` in Example A." RFC-008's lifecycle definitions use `besluit_datum` at the BEHANDELING stage, not `beschikking_datum`. A boete procedure needs its own lifecycle with `overtreding_datum` as a stage input — that lifecycle isn't modelled in RFC-008 yet. Either use the established `$besluit_datum` or explicitly note that a boete lifecycle adds these new stage inputs (and where they'll be defined).

---

🟡 Minor: failure path testing missing the `as_of` before `valid_from` case

Test case 5 covers `as_of` past `valid_to` (law ended). The symmetric case — `as_of` before `valid_from` (law not yet in force) — is equally likely in practice (e.g. an `overtreding_datum` that predates the law). A sixth test case would complete the symmetry.

---

🟡 Minor: unaddressed failure mode when `as_of: $param` and param is absent

§2 allows `as_of: $param` but the "Still open" section and Implementation Notes are silent on the runtime case where the parameter isn't supplied. Should the engine fall back to `calculation_date` or error? Given RFC-015's zero-domain-knowledge policy a silent fallback seems wrong — worth adding to the open items.

---

🟡 Minor: typo "corpus AWB" should be "corpus Awb"

In the Example A footnote: "Awb 7:11 is not yet in the corpus AWB" — every other occurrence in this document uses "Awb".

---

Verified

• `source` in `schema/v0.5.3/schema.json` has `"additionalProperties": false` — the schema-version-bump claim is correct.
• All referenced RFCs (001, 003, 007, 008, 013, 014, 015, 019) exist in `docs/src/content/rfcs/`. `/reference/glossary` resolves. RFC-001 §8 ("Temporal Specifications") is the correct section for the three-axes table citation.

[claude]

RFC-020: Date-Aware Reference Resolution — review

One 🟡 minor finding. The legal grounding, section cross-references (RFC-019 §3/§4, RFC-007 §3), and worked-example logic are all sound.

---

Legal faithfulness

Citations verified:

• Awb art. 7:11 lid 1 and 5:46 lid 4 (BWBR0005537) ✓
• Art. 1 lid 2 Sr (BWBR0001854) ✓
• Aanwijzingen 3.47 / 5.60 / 5.61 / 5.64 (BWBR0005730) ✓
• All six ECLI anchors consistent with the body text ✓

The four lex-mitior boundaries (mandatory, punitive-only, gewijzigd inzicht, selector-in-law) are correct and important for keeping the engine free of domain knowledge.

Schema / YAML examples

🟡 Minor — Example C values uses flow-sequence style inconsistent with corpus convention

      values: [$boete_overtredingsmoment, $boete_besluitmoment]

Existing corpus files (e.g. wet_op_de_zorgtoeslag/2025-01-01.yaml) always use block-sequence style:

      values:
        - $boete_overtredingsmoment
        - $boete_besluitmoment

Both are valid YAML and schema-compliant, but the flow form is inconsistent with every other values array in the corpus and will likely be copy-pasted during implementation. Worth normalising before this ships as a reference example.

Cross-law reference integrity

The source.additionalProperties: false constraint is correctly identified as requiring a schema minor bump. No new source.regulation slugs are introduced (all examples are illustrative with noted corpus gaps).

Testing section

The six listed BDD test cases cover the key paths well (ex nunc/ex tunc, statische verwijzing, lex mitior, propagation, both failure directions). One gap: there is no test case for IoC propagation with as_of — the case stated in §5 where an outer as_of selects implementing regulations at the propagated date rather than calculation_date. Given that this is the most novel part of §5 and the one most likely to be implemented incorrectly, it warrants its own scenario alongside the existing six.

Still Open

The open points are well-scoped. The as_of: $param absent at runtime question should resolve to a strict error (as the RFC leans toward) rather than a silent fallback to calculation_date — the RFC's reasoning here (RFC-015 zero-domain-knowledge, mirroring missing required inputs) is correct.

[claude]

RFC-020: Date-Aware Reference Resolution (as_of) — Review

Scope: This PR adds only docs/src/content/rfcs/rfc-020.md. The applicable review dimensions are legal faithfulness of the proposed design, coherence with existing RFCs, and correctness of the worked examples.

RFC-019 is confirmed merged (file present in repo); the diff is rfc-020 only. The MIN operation used in Example C is valid per the current schema (arithmeticOperation.operation enum includes MIN/MAX). The source.additionalProperties: false constraint is correctly identified as requiring a minor schema bump.

---

Legal Faithfulness

No issues. Awb 7:11 lid 1 text is quoted accurately. Art. 5:46 lid 4 Awb / art. 1 lid 2 Sr grounding for lex mitior is correct. ECLI format is valid throughout (ECLI:NL:RVS:..., ECLI:NL:CBB:...). Attribution of onmiddellijke werking to drafting convention (not statutory law) is correctly hedged. The four lex-mitior faithfulness boundaries in §4 are well-reasoned.

---

Issues

🟡 Minor — as_of scope not conditioned on regulation being present

The source object has regulation as optional (schema: "Omit for external data sources that must be resolved outside the YAML"). as_of on a source without regulation has no defined semantics — there is no law to select a version of. The RFC and Implementation Notes do not clarify whether:

• as_of is a schema-level error when regulation is absent, or
• it is silently ignored.

Given additionalProperties: false, the schema bump is the right place to enforce this, e.g. via if: {required: ["regulation"]}, then: {properties: {as_of: {...}}}. Worth specifying before implementation.

---

🟡 Minor — as_of type union left implicit in Implementation Notes

The notes say "literal date or $-parameter" without specifying the JSON Schema encoding. A plain {type: string} would admit malformed dates ("2000-99-99") and misspelled params ("besluit_datum" without $). The existing pattern for this union is oneOf: [variableReference, {type: string, format: date}] — variableReference already carries the ^\$[A-Za-z_]... pattern. Naming this in the Implementation Notes avoids implementation ambiguity and ensures corpus validation stays strict.

---

🟡 Minor — Testing item 6 conflates two different SelectionReason subtypes

Item 5: as_of past valid_to → maps to RFC-019 §3's EndedOn(date).
Item 6: as_of before valid_from → maps to RFC-019 §3's NotYetInForce.

Item 6 currently says "yields the same SelectionReason error" — but these are different subtypes with different messages ("nog niet in werking" vs "laatst geldig t/m <valid_to>"). Should read "yields a SelectionReason error (NotYetInForce)" to stay consistent with RFC-019 §3's typed-reason taxonomy.

---

🟡 Minor — Cycle detection: regressive-date chains not addressed

The RFC correctly says include the resolved as_of date in cycle-detection keys. This catches same-date self-references. It does not catch a chain where law A (at D) references law A (at D−1 via inner as_of: $earlier_param) which in turn references law A (at D−2), etc. — each call has a unique key. In practice, corpus YAMLs are static and cannot self-generate older as_of values, but the RFC should note that RFC-007's existing depth limit is the backstop for this case, or explicitly state this as a deliberate out-of-scope constraint.

---

Still-Open items

The four open items are honestly disclosed and appropriately deferred. The lean toward "strict resolution error" for absent as_of: $param (last item) is the right call; marking it as decided rather than likely would strengthen the RFC without requiring implementation work.

---

No critical or significant issues. The legal grounding is thorough, the design composes cleanly with RFC-019, and the YAML examples stay within the existing operation grammar.