test: add reproducible domain table generator

.github/workflows/domain-tables.yml

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: Domain Table Generator
+
+on:
+  pull_request:
+    paths:
+      - "tools/generate_domain_tables.py"
+      - "tools/tests/test_generate_domain_tables.py"
+      - "resources/domains/**"
+      - ".github/workflows/domain-tables.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  deterministic-generator:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Test deterministic XLSX normalization
+        run: python3 -m unittest tools/tests/test_generate_domain_tables.py

resources/domains/README.md

@@ -38,3 +38,26 @@ When an official annex changes:
 4. update the version constant in `OfficialDomainCatalog`;
 5. update cardinality and representative-code tests;
 6. review downstream mapping changes explicitly instead of silently coercing old values.
+
+
+## Reproducible generation
+
+The snapshots are generated directly from the three official XLSX annexes with only the Python
+standard library:
+
+```bash
+python3 tools/generate_domain_tables.py \
+  --annex-a /path/to/ANEXO_A.xlsx \
+  --annex-b /path/to/ANEXO_B.xlsx \
+  --annex-c /path/to/ANEXO_C.xlsx \
+  --output resources/domains
+```
+
+Use `--check` to compare regenerated output with the committed snapshots. The command validates
+the expected official cardinalities (5,571 municipalities/general localities, 250 countries,
+338 national service codes, 918 nine-digit NBS codes and 26 operation indicators) before writing
+or accepting output.
+
+The generator reads XLSX as ZIP/XML, honors cell references and vertically merged cells, derives
+UF only from the stable IBGE prefix map, and rejects an unexpected cardinality. A network-free CI
+fixture exercises the same parser and proves deterministic output.