Skip to content
This repository was archived by the owner on Jun 6, 2026. It is now read-only.

feat: add EU source records and cross-border conditions — #40 PR 1/4 (foundation)#47

Merged
TommiLindfors merged 1 commit into
clarvia-org:mainfrom
HirenGajjar:feat/cross-border-foundation
May 30, 2026
Merged

feat: add EU source records and cross-border conditions — #40 PR 1/4 (foundation)#47
TommiLindfors merged 1 commit into
clarvia-org:mainfrom
HirenGajjar:feat/cross-border-foundation

Conversation

@HirenGajjar
Copy link
Copy Markdown
Collaborator

Part 1 of 4 for issue #40. This PR establishes the shared foundation — EU-level source records and cross-border conditions — that all four corridor PRs will reference. It must merge before PR 2 (France), PR 3 (Germany), and PR 4 (Belgium + Portugal).


Context and approach

Issue #40 is structured as 4 sequential PRs. This first PR contains no corridor-specific content — only the infrastructure that is shared across all corridors:

  • Two EU regulations that provide the legal basis for cross-border succession and pension routing
  • Five conditions that trigger cross-border logic in the workflow engine

The corridor scenario files (PR 2–4) will reference condition:deceased-is-frontalier, condition:survivor-resides-abroad, etc. by ID. Those references will only resolve correctly after this PR merges into main.


Files added

data/sources/eu/brussels-iv-regulation.yaml

URL verified: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32012R0650 — loads correctly on EUR-Lex, title confirmed as "Regulation (EU) No 650/2012".

  • source_type: regulation — EU Regulations are binding law, not guidance or portal pages
  • verification_status: structured-from-source — URL verified and key provisions read
  • jurisdiction.country: EU — valid per ^[A-Z]{2}$ pattern; appropriate for an EU-wide regulation
  • institution_ids: [] — no EU institution record exists yet in the data model
  • Trilingual titles and descriptions (EN/FR/DE)

Key provisions documented in notes:

  • Art. 21: succession governed by law of habitual residence at death
  • Art. 22: deceased may choose nationality's law by explicit declaration
  • Art. 62–73: European Certificate of Succession (ECS), valid across all member states
  • Applies in all EU member states except Denmark and Ireland for succession matters

data/sources/eu/social-security-coordination.yaml

URL verified: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32004R0883 — loads correctly, title confirmed as "Regulation (EC) No 883/2004".

  • source_type: regulation
  • verification_status: structured-from-source
  • Current consolidated version: 31/07/2019
  • Applies to EU member states plus EEA and Switzerland
  • Trilingual titles and descriptions (EN/FR/DE)

Key facts documented in notes:

  • For frontaliers: survivor pension typically paid by country of last employment
  • Coordinated via national liaison bodies — CNAP is Luxembourg's liaison
  • Covers survivor benefits, pension aggregation, and cross-border claims routing

data/conditions/common/deceased-is-foreign-national.yaml

  • condition_type: nationality
  • expression.field: deceased_nationality, operator: not_equals, value: LU
  • References source:eu:brussels-iv-regulation
  • Note: relevant for ~47% of Luxembourg residents who hold non-LU nationality

data/conditions/common/deceased-is-frontalier.yaml

  • condition_type: cross_border
  • expression.field: deceased_work_country, operator: not_equals, value: LU
  • References source:eu:social-security-coordination
  • Note: ~225,000 frontaliers commute to Luxembourg daily — France (~120,000), Germany (~55,000), Belgium (~50,000)

data/conditions/common/survivor-resides-abroad.yaml

  • condition_type: heir_location
  • expression.field: survivor_residence_country, operator: not_equals, value: LU
  • References both source:eu:social-security-coordination and source:eu:brussels-iv-regulation
  • Affects pension claim routing, death certificate translation/apostille requirements, and which country's administrative processes apply

data/conditions/common/assets-in-multiple-jurisdictions.yaml

  • condition_type: asset_location
  • expression.field: asset_countries, operator: count_greater_than, value: 1
  • References source:eu:brussels-iv-regulation
  • Note: European Certificate of Succession can be used across member states; cross-border estates may require coordination between notaries in multiple jurisdictions

data/conditions/common/repatriation-of-remains.yaml

  • condition_type: cross_border
  • expression.field: repatriation_requested, operator: equals, value: true
  • References source:lu:guichet:death-life-event — no EU regulation specifically governs this; the 1973 Strasbourg Convention applies for EU corridors
  • Note: requires laissez-passer mortuaire from Luxembourg commune; cremated remains have fewer restrictions than body transport

Schema compliance notes

  • Read all schemas in schemas/v0.1/ before writing any file
  • Followed exact pattern of existing data/conditions/common/death-in-jurisdiction.yaml for expression block structure
  • jurisdiction.country: EU passes ^[A-Z]{2}$ validation — deliberately chosen for EU-wide regulations
  • source:eu:... IDs pass ^source:[a-z]{2}:[a-z0-9-]+... pattern — eu matches [a-z]{2}
  • All additionalProperties: false constraints respected — no extra fields added
  • All condition source_ids reference sources that either already exist in main or are created in this same PR

What PR 2–4 will add

  • PR 2: scenario:corridor-lu-fr + 2 FR sources (service-public, info-retraite) + 2 FR institutions (CARSAT, SCEC)
  • PR 3: scenario:corridor-lu-de + 2 DE sources (DRV) + 1 DE institution (DRV)
  • PR 4: scenario:corridor-lu-be + scenario:corridor-lu-pt + BE/PT sources and institutions

Verified

  • python3 scripts/validate.py — passes (19 data files, up from 12)
  • All 7 trailing newlines confirmed 0a
  • 7 new files, 0 existing files modified
  • Both EUR-Lex URLs verified loading in browser before writing
  • git status confirmed no unintended changes

@TommiLindfors TommiLindfors merged commit d03d54b into clarvia-org:main May 30, 2026
1 check passed
@TommiLindfors
Copy link
Copy Markdown
Contributor

Merged! Excellent foundation work @HirenGajjar. A few things that stood out:

  • Article references in the notes (Art. 21, 22, 62-73 for Brussels IV) — exactly what source-backed means
  • Using \jurisdiction.country: EU\ for EU-wide regulations is a smart convention
  • The expression blocks on the conditions are well-structured and consistent with the existing \death-in-jurisdiction\ pattern
  • Good note on the 1973 Strasbourg Convention for repatriation — that's real domain knowledge

Foundation is in main now, so PRs 2-4 can reference these IDs. Thirteen merged PRs and counting.

TommiLindfors pushed a commit that referenced this pull request May 30, 2026
Part 2 of 4 for issue #40. Depends on PR 1/4 (#47, now merged). Adds the
France corridor: 2 French sources, 2 French institutions, and the LU–FR
corridor scenario.

---

## Context

France is the largest frontalier corridor for Luxembourg — approximately
120,000 workers cross the border daily. This PR encodes the sources and
institutions a Luxembourg-connected family with French ties would
interact with, and wires them into a corridor scenario that references
the cross-border conditions and EU regulations from PR 1.

---

## Files added

### `data/sources/fr/service-public-deces.yaml`

**URL verified:**
https://www.service-public.fr/particuliers/vosdroits/F16507 — loads
correctly, title confirmed as "Un proche est décédé". Last verified on
service-public.fr: 01 janvier 2026.

- `source_type: government_portal`
- `verification_status: source-checked`
- Covers the full French bereavement journey: funeral organisation,
institution notifications, succession steps, and time-sensitive
obligations

---

### `data/sources/fr/info-retraite-reversion.yaml`

**URL verified:** https://www.info-retraite.fr — loads correctly. GIP
Union Retraite official portal.

- `source_type: institutional_page`
- `verification_status: source-checked`
- Key research finding documented in notes: if the survivor pension
(pension de réversion) is filed within 1 year of death, the start date
is the first day of the month after death. A single online request
covers all French base and complementary schemes.

---

### `data/institutions/fr/carsat.yaml`

**URL verified:** https://www.carsat-alsacemoselle.fr — loads correctly.

- `id: institution:fr:carsat-alsace-moselle` — deliberately the
Alsace-Moselle CARSAT, not a generic CARSAT record, because this CARSAT
directly borders Luxembourg and specifically handles Luxembourg
frontalier pension coordination
- Documents the 2026 "mixed career" form (formulaire carrière mixte)
introduced to expedite coordination with CNAP via form P5000
- Organises personalised advisory sessions with Luxembourg CNAP
representatives

---

### `data/institutions/fr/scec.yaml`

**URL verified:**
https://www.diplomatie.gouv.fr/fr/services-aux-francais/etat-civil-et-nationalite-francaise/
— loads correctly (general civil status section).

- `id: institution:fr:scec`
- `verification_status: discovered` — the specific SCEC transcription
page content was not fully verified; honest status applied
- Documents that for a French national who dies in Luxembourg, the
family must request transcription of the Luxembourg death certificate
through SCEC for French civil registry records and succession procedures
- SCEC is located in Nantes and operates under the Ministry of Europe
and Foreign Affairs

---

### `data/scenarios/corridor-lu-fr.yaml`

- `scenario_type: corridor`
- `countries: [LU, FR]`
- `publication_status: draft`
- References all 5 conditions from PR 1: `deceased-is-foreign-national`,
`deceased-is-frontalier`, `survivor-resides-abroad`,
`assets-in-multiple-jurisdictions`, `repatriation-of-remains`
- References both EU sources from PR 1 and both FR sources from this PR

**Key corridor facts documented in notes:**
- Survivor pension filed via Info Retraite (single request, all French
schemes)
- CARSAT Alsace-Moselle coordinates with CNAP via P5000 form
- Luxembourg death certificate requires SCEC transcription for French
civil registry
- Succession governed by Brussels IV habitual residence rule

---

## Schema compliance

- Read all schemas before writing — `additionalProperties: false`
respected throughout
- Institution `official_site` field confirmed loading for all records
- `source_ids` in institutions reference sources created in this same PR
- Scenario `condition_ids` reference conditions merged in PR 1 —
dependency respected

---

## What PR 3 will add

- `scenario:corridor-lu-de` + 2 DE sources (DRV pages) + 1 DE
institution (DRV)

---

## Verified

- `python3 scripts/validate.py` — passes (24 data files, up from 19)
- All 5 trailing newlines confirmed `0a`
- 5 new files, 0 existing files modified
- All source and institution URLs verified loading in browser before
writing
- `git status` confirmed no unintended changes
TommiLindfors pushed a commit that referenced this pull request May 31, 2026
Part 4 of 4 for issue #40. Completes the cross-border corridor
infrastructure with Belgium and Portugal.

---

## Context

This PR adds the two remaining corridors:
- **Belgium** — ~50,000 daily frontaliers, third largest corridor
- **Portugal** — ~100,000 residents, the largest foreign national
community in Luxembourg

---

## Files added

### `data/sources/be/belgium-be-deces.yaml`

**URL verified:** https://www.belgium.be/fr/famille/deces — loads
correctly, title confirmed as "Décès".

- `source_type: government_portal`
- `verification_status: source-checked`
- `languages: [fr, nl, de]` — belgium.be is trilingual
- Includes `title_fr`, `title_de`, `description_fr`, `description_de`

**Key facts documented in notes (from issue #40 research):**
- Death must be declared to the municipality where the person died,
usually handled by the undertaker
- Death certificate is then forwarded to the municipality of last
residence
- Succession duties in Belgium are regional and depend on fiscal
residence

---

### `data/institutions/be/sfp.yaml`

**URL verified:** https://www.sfpd.fgov.be — loads correctly as "Federal
Pensions Service".

- `id: institution:be:sfp`
- `verification_status: structured-from-source`
- `languages: [fr, nl, de]` — Belgian trilingual institution (SFP in
French, FPD in Dutch)
- References `source:be:belgium-be-deces`

**Key facts documented in notes:**
- Survivor pension applications submitted via mypension.be
- Coordinates with CNAP via EU social security coordination for
cross-border cases
- Covers ~50,000 Belgian frontaliers

---

### `data/scenarios/corridor-lu-be.yaml`

- `scenario_type: corridor`
- `countries: [LU, BE]`
- `publication_status: draft`
- References all 5 PR1 conditions and both EU sources + BE source

---

### `data/sources/pt/gov-pt-obito.yaml`

**URL:** https://eportugal.gov.pt/en/temas/familia/morte — identified
from official ePortugal portal structure; page was inaccessible during
creation.

- `source_type: government_portal`
- `verification_status: discovered` — honest status, URL could not be
confirmed loading
- `last_verified_at: null`
- Notes explicitly state full content verification requires further
access

**Key facts encoded from issue #40 research:**
- Death of a Portuguese citizen abroad must be declared in Portugal
- Survivor pension (pensão de sobrevivência) requires minimum 36 months
of contributions
- Application via Segurança Social Direta using form RP 5075

---

### `data/institutions/pt/seguranca-social.yaml`

**URL:** https://www.seg-social.pt — confirmed loading from research.

- `id: institution:pt:seguranca-social`
- `verification_status: discovered` — consistent with PT source status
- `languages: [pt]`

**Key facts documented in notes:**
- Portugal has the largest foreign national community in Luxembourg
(~100,000 residents)
- 36-month contribution requirement for survivor pension
- Death of Portuguese national abroad must be registered in Portugal via
consular services
- Centro Nacional de Pensões (CNP) within ISS handles international
pension coordination

---

### `data/scenarios/corridor-lu-pt.yaml`

- `scenario_type: corridor`
- `countries: [LU, PT]`
- `publication_status: draft`
- Notes explicitly flag that further source verification is needed for
full PT corridor detail

---

## Verification status honesty

Belgium sources are `source-checked` — URLs verified loading, content
confirmed.
Portugal sources are `discovered` — URL identified from official portal
structure but could not be verified loading during creation. This is
consistent with issue #40's own note: "Detailed survivor-pension routing
and death transcription process need further verification."

---

## Issue #40 complete

With this PR all four corridors are now in main:
- PR 1/4 (#47) — EU foundation (conditions + EU regulations) ✅
- PR 2/4 (#48) — France corridor ✅
- PR 3/4 (#49) — Germany corridor ✅
- PR 4/4 (this PR) — Belgium + Portugal corridors

Total new files across all 4 PRs: 25 files covering 2 EU regulations, 5
cross-border conditions, 4 corridor scenarios, 6 foreign sources, 5
foreign institutions.

---

## Schema compliance

- All schemas read before writing — `additionalProperties: false`
respected throughout
- All condition IDs reference conditions from PR 1 (merged)
- All EU source IDs reference sources from PR 1 (merged)
- `institution_ids` and `source_ids` cross-references consistent within
each PR

---

## Verified

- `python3 scripts/validate.py` — passes (34 data files, up from 28)
- All 6 trailing newlines confirmed `0a`
- 6 new files, 0 existing files modified
- `git status` confirmed no unintended changes
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants