refactor: replace Python domain utilities with isolated PHP tooling

.github/actions/setup-project-php/action.yml

@@ -0,0 +1,43 @@
+# SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: Set up project PHP
+description: Use the PHP compatibility contract in the root composer.json
+inputs:
+  php-version:
+    description: Explicit CI matrix version, or empty for the Composer minimum
+    required: false
+    default: ""
+  extensions:
+    description: Extensions needed by the invoking job
+    required: false
+    default: "openssl, dom, soap"
+  coverage:
+    description: Coverage driver
+    required: false
+    default: "none"
+  ini-file:
+    description: PHP INI preset
+    required: false
+    default: ""
+  ini-values:
+    description: Additional INI values
+    required: false
+    default: ""
+runs:
+  using: composite
+  steps:
+    - name: Validate root Composer PHP policy
+      id: php-policy
+      shell: bash
+      run: |
+        php tools/bin/ci-php.php validate
+        echo "minimum=$(php tools/bin/ci-php.php minimum)" >> "$GITHUB_OUTPUT"
+    - name: Install PHP
+      uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2
+      with:
+        php-version: ${{ inputs.php-version || steps.php-policy.outputs.minimum }}
+        extensions: ${{ inputs.extensions }}
+        coverage: ${{ inputs.coverage }}
+        ini-file: ${{ inputs.ini-file }}
+        ini-values: ${{ inputs.ini-values }}

.github/workflows/domain-tables.yml

@@ -6,10 +6,13 @@ name: Domain Table Generator
 on:
   pull_request:
     paths:
-      - "tools/generate_domain_tables.py"
-      - "tools/tests/test_generate_domain_tables.py"
+      - "tools/**"
+      - "vendor-bin/domains/**"
       - "resources/domains/**"
+      - "composer.json"
       - ".github/workflows/domain-tables.yml"
+      - ".github/actions/setup-project-php/**"
+  workflow_dispatch:
 
 permissions:
   contents: read
@@ -21,5 +24,17 @@ jobs:
       - 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
+      - name: Set up PHP from Composer
+        uses: ./.github/actions/setup-project-php
+        with:
+          extensions: dom, mbstring, zip, gd, xml, xmlreader, xmlwriter, simplexml, fileinfo
+      - name: Install isolated domain tooling
+        run: composer --working-dir=vendor-bin/domains install --prefer-dist --no-progress --no-interaction
+      - name: Validate root and isolated Composer manifests
+        run: |
+          composer validate --strict
+          composer --working-dir=vendor-bin/domains validate --strict
+      - name: Run offline deterministic PHPUnit cases
+        run: composer --working-dir=vendor-bin/domains run test
+      - name: Lint PHP domain tools
+        run: find tools -type f -name '*.php' -print0 | xargs -0 -n 1 php -l

.github/workflows/lint-php-cs.yml

@@ -24,12 +24,10 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Set up PHP 8.2
-        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2
+      - name: Set up PHP from Composer
+        uses: ./.github/actions/setup-project-php
         with:
-          php-version: "8.2"
           extensions: openssl, dom, soap
-          coverage: none
           ini-file: development
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/minimum-dependencies.yml

@@ -22,12 +22,10 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Set up PHP 8.2
-        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2
+      - name: Set up PHP from Composer
+        uses: ./.github/actions/setup-project-php
         with:
-          php-version: "8.2"
           extensions: openssl, dom, soap
-          coverage: none
           ini-file: development
           ini-values: disable_functions=
         env:

.github/workflows/nt009-evidence.yml

@@ -0,0 +1,50 @@
+# SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: NT009 Source Evidence
+
+on:
+  pull_request:
+    paths:
+      - "tools/**"
+      - "composer.json"
+      - "vendor-bin/domains/**"
+      - "resources/domains/**"
+      - ".github/workflows/nt009-evidence.yml"
+      - ".github/actions/setup-project-php/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  optional-official-evidence:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up PHP from Composer
+        uses: ./.github/actions/setup-project-php
+        with:
+          extensions: dom, mbstring, zip, gd, xml, xmlreader, xmlwriter, simplexml, fileinfo
+      - name: Install isolated domain tooling
+        run: composer --working-dir=vendor-bin/domains install --prefer-dist --no-progress --no-interaction
+      - name: Verify original XLSX hashes and compare official NT009 data
+        run: |
+          php tools/bin/domains.php audit \
+            --download-dir="${{ runner.temp }}/nt009" \
+            --report="${{ runner.temp }}/nt009-comparison.json"
+      - name: Verify versioned Annex VII against all published XLSX rows
+        run: php tools/bin/domains.php verify-indicators --annex-vii="${{ runner.temp }}/nt009/annex-vii-nt009.xlsx"
+      - name: Retain full evidence for manual review
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: nt009-official-source-evidence
+          path: |
+            ${{ runner.temp }}/nt009-comparison.json
+            ${{ runner.temp }}/nt009/*.xlsx
+          if-no-files-found: warn
+          retention-days: 30

.github/workflows/official-snapshot-reproduction.yml

@@ -0,0 +1,49 @@
+# SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: Official Snapshot Reproduction
+
+on:
+  pull_request:
+    paths:
+      - "tools/**"
+      - "composer.json"
+      - "vendor-bin/domains/**"
+      - "resources/domains/**"
+      - ".github/workflows/official-snapshot-reproduction.yml"
+      - ".github/actions/setup-project-php/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  advisory-production-snapshot-reproduction:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up PHP from Composer
+        uses: ./.github/actions/setup-project-php
+        with:
+          extensions: dom, mbstring, zip, gd, xml, xmlreader, xmlwriter, simplexml, fileinfo
+      - name: Install isolated domain tooling
+        run: composer --working-dir=vendor-bin/domains install --prefer-dist --no-progress --no-interaction
+      - name: Download checksum-verified official production annexes
+        run: php tools/bin/domains.php download --ids=annex-a,annex-b,annex-c --output="${{ runner.temp }}/official"
+      - name: Compare regenerated output byte-for-byte with versioned snapshots
+        run: |
+          php tools/bin/domains.php check \
+            --annex-a="${{ runner.temp }}/official/annex-a.xlsx" \
+            --annex-b="${{ runner.temp }}/official/annex-b.xlsx" \
+            --annex-c="${{ runner.temp }}/official/annex-c.xlsx"
+      - name: Preserve source workbooks for manual review
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: official-production-domain-sources
+          path: ${{ runner.temp }}/official/*.xlsx
+          if-no-files-found: warn
+          retention-days: 14

.github/workflows/phpunit.yml

@@ -13,26 +13,44 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  php-policy:
+    name: PHP versions from root Composer
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.policy.outputs.matrix }}
+      primary: ${{ steps.policy.outputs.primary }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Read CI PHP matrix and primary from composer.json
+        id: policy
+        run: |
+          php tools/bin/ci-php.php validate
+          echo "matrix=$(php tools/bin/ci-php.php matrix)" >> "$GITHUB_OUTPUT"
+          echo "primary=$(php tools/bin/ci-php.php primary)" >> "$GITHUB_OUTPUT"
+
   compatibility:
     name: PHP ${{ matrix.php-version }}
     runs-on: ubuntu-latest
+    needs: php-policy
 
     strategy:
       matrix:
-        php-version: ["8.2", "8.3", "8.4"]
+        php-version: ${{ fromJSON(needs.php-policy.outputs.matrix) }}
 
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
-      - name: Set up PHP ${{ matrix.php-version }}
-        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2
+      - name: Set up PHP from Composer matrix
+        uses: ./.github/actions/setup-project-php
         with:
           php-version: ${{ matrix.php-version }}
           extensions: openssl, dom, soap
-          coverage: none
           ini-file: development
           ini-values: disable_functions=
         env:
@@ -48,7 +66,7 @@ jobs:
         run: composer run test:unit
 
       - name: Run integration tests when certificate secrets are present
-        if: ${{ matrix.php-version == '8.3' }}
+        if: ${{ matrix.php-version == needs.php-policy.outputs.primary }}
         env:
           NFSE_CLIENT_CERT_B64: ${{ secrets.NFSE_CLIENT_CERT_B64 }}
           NFSE_CLIENT_KEY_B64: ${{ secrets.NFSE_CLIENT_KEY_B64 }}
@@ -64,17 +82,18 @@ jobs:
   coverage:
     name: Coverage
     runs-on: ubuntu-latest
+    needs: php-policy
 
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
-      - name: Set up PHP 8.3
-        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2
+      - name: Set up PHP from Composer primary
+        uses: ./.github/actions/setup-project-php
         with:
-          php-version: "8.3"
+          php-version: ${{ needs.php-policy.outputs.primary }}
           extensions: openssl, dom, soap
           coverage: xdebug
           ini-file: development

.github/workflows/psalm.yml

@@ -24,12 +24,10 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Set up PHP 8.2
-        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2
+      - name: Set up PHP from Composer
+        uses: ./.github/actions/setup-project-php
         with:
-          php-version: "8.2"
           extensions: openssl, dom, soap
-          coverage: none
           ini-file: development
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/source-watch.yml

@@ -0,0 +1,36 @@
+# SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: Official NFS-e Source Watch
+
+on:
+  schedule:
+    - cron: "17 9 * * 1-5"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  check-published-files:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up PHP from Composer
+        uses: ./.github/actions/setup-project-php
+        with:
+          extensions: dom, mbstring, zip, gd, xml, xmlreader, xmlwriter, simplexml, fileinfo
+      - name: Install isolated domain tooling
+        run: composer --working-dir=vendor-bin/domains install --prefer-dist --no-progress --no-interaction
+      - name: Compare official source checksums
+        run: php tools/bin/domains.php watch --report="${{ runner.temp }}/nfse-sources-report.json"
+      - name: Retain diff evidence without modifying the repository
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: official-nfse-source-check
+          path: ${{ runner.temp }}/nfse-sources-report.json
+          if-no-files-found: warn
+          retention-days: 30

.gitignore

@@ -6,3 +6,4 @@
 /.env
 /.env.local
 /.secrets/
+/vendor-bin/domains/vendor/

.php-cs-fixer.dist.php

@@ -12,6 +12,7 @@
     ->in([
         __DIR__ . '/src',
         __DIR__ . '/tests',
+        __DIR__ . '/tools',
     ])
     ->name('*.php')
     ->notPath('fixtures');

REUSE.toml

@@ -13,7 +13,10 @@ default-copyright = "2026 LibreCode coop and contributors"
 [[annotations]]
 path = [
     ".gitignore",
-    "composer.json"
+    "composer.json",
+    "vendor-bin/domains/composer.json",
+    "vendor-bin/domains/composer.lock",
+    "resources/domains/sources.json"
 ]
 precedence = "aggregate"
 SPDX-FileCopyrightText = "2026 LibreCode coop and contributors"