Implement version-aware NT009 v1.01 DPS/IBSCBS contract #95

Goal

Implement version-aware support for the DPS/IBSCBS contract defined by Nota Técnica SE/CGNFS-e nº 009 v1.01 (2026-10-01), using Annex VI v1.04.01 and Annex VII v1.03.00.

Preserve compatibility with existing production contracts. Publishing a new normative layout must not automatically change the XML emitted by existing consumers.

Verified baseline — 2026-10-08

The following work has already been merged:

• PR refactor: replace Python domain utilities with isolated PHP tooling #97: PHP-only official annex tooling, isolated PhpSpreadsheet, reproducible generators, source monitoring, CI improvements and Composer-based PHP version configuration.
• PR feat: audit official NT009 indicators and layout evidence in PHP (#95) #99: NT009 source audit, a versioned Annex VII snapshot and deterministic comparisons against the official workbooks.

The repository now includes:

• resources/domains/indicadores-operacao-ibscbs-v1.01.tsv: 26 indicators from the existing production Annex C.
• resources/domains/indicadores-operacao-ibscbs-v1.03.00.tsv: all 40 indicators from Annex VII v1.03.00.
• resources/domains/sources.json: source versions, official URLs and observed checksums.
• tools/bin/domains.php: commands for downloading, auditing, generating and verifying official tables.
• docs/NT009-SOURCE-AUDIT.md: provenance and comparison evidence.

These deliverables must be reused, not reimplemented.

Remaining gaps

• OfficialDomainCatalog still exposes Annex C v1.01 as its default operation-indicator domain.
• DpsData represents only the currently implemented IBS/CBS fields.
• XmlBuilder::buildIbsCbs() uses the previous field structure and requires certain values unconditionally.
• DpsSchemaValidator supports only the existing schema version 1.01, sourced from the production package dated 2026-02-09.
• The published NT009 workbook has not yet been converted into a complete, independently reviewed implementation contract.

The official production and restricted-production documentation currently list their respective XSD packages separately. The availability and effective date of an NT009-compatible schema must be independently verified before enabling a new emission contract.

Required implementation

1. Establish the applicable official contract

Compare the implemented DPS/IBSCBS structure against NT009 v1.01 / Annex VI v1.04.01 and the applicable official XSD packages.

Produce a reviewable contract matrix covering:

• XML path, field name and parent group.
• Type, format, cardinality and element ordering.
• Mandatory, optional and conditional occurrence.
• Conditions and business-rule identifiers, where officially documented.
• Previous and proposed contract versions.
• Production versus restricted-production applicability.
• Effective date and supporting official source.
• Existing DTO, builder, validation and test coverage.

Do not infer mandatory behavior merely from a field's presence in the workbook.

Verify whether the applicable XSD has actually been published or deployed. Distinguish schema version, package date, source checksum and environment: different packages may share the same numeric schema version.

2. Implement version-aware DPS/IBSCBS serialization

Review and update:

• src/Dto/DpsData.php
• src/Xml/XmlBuilder.php
• src/Xml/DpsSchemaValidator.php
• Relevant domain validators and official schema fixtures.

Implement the verified NT009 fields, groups, ordering and conditional requirements.

In particular, review the placement and conditions of CST, cClassTrib, gIBSCBS, cIndOp, indDest, finNFSe and any additional fields identified by the official comparison.

Requirements:

• Preserve existing XML output when the caller continues using the existing contract.
• Provide explicit contract/version selection where technically necessary.
• Do not activate a newly published contract automatically based solely on its publication date.
• Do not force every documented IBS/CBS field to be present in every operation.
• Reject genuinely invalid or incomplete configurations under the selected contract, with actionable diagnostics.
• Do not infer tax classification, tax amounts or taxpayer-specific fiscal rules inside this protocol library.
• Document public API incompatibilities and migration steps if an additive API is insufficient.

If a necessary official XSD or effective-date confirmation is unavailable, document the blocker rather than inventing schema semantics or declaring the new contract production-ready.

3. Integrate versioned operation-indicator domains

Reuse the already committed Annex VII v1.03.00 snapshot.

Provide the necessary version-aware catalog access and metadata without silently changing the existing behavior of OfficialDomainCatalog::operationIndicator().

Requirements:

• Preserve all 40 published indicator records without invented codes or descriptions.
• Preserve the previous 26-code catalog for the applicable earlier contract.
• Validate codes against the explicitly selected applicable domain.
• Distinguish published codes from codes applicable to a particular document type when supported by authoritative rules.
• Avoid treating consultative correlations as mandatory validation.
• Update metadata and tests without losing historical version information.

Annex VIII remains advisory-only while the official portal states that no production or RTC-pilot business rules are based on it.

4. Tests and evidence

Add deterministic tests for:

• Legacy DPS output remaining unchanged.
• New contract XML hierarchy, ordering and formatting.
• Mandatory, optional, conditional and invalid configurations.
• Cases where an optional field is omitted legitimately.
• Distinct contract selections and version transitions.
• Valid and invalid operation indicators under each supported version.
• Official XSD validation for every contract claimed as supported.
• Rejection of unsupported versions.
• Schema package integrity and source provenance.

Reuse the existing official-source tooling and tests. Do not introduce another XLSX parser, a separate generation language or runtime network dependencies.

Execute all applicable checks, including:

• PHPUnit unit and contract tests.
• Psalm.
• PHP CS Fixer.
• Minimum-dependency and supported-PHP compatibility tests.
• Official schema integrity tests.
• Deterministic annex verification and the applicable GitHub Actions workflows.

Tests against live fiscal systems, when appropriate and authorized, must use the correct environment and must not replace deterministic contract tests.

5. Downstream compatibility

Inspect LibreCodeCoop/akaunting-nfse, whose 3rdparty/composer.json currently pins a specific nfse-php commit.

Document:

• Whether its existing DTO construction and emission calls remain compatible.
• Any new arguments, fields or version-selection requirements.
• The exact tested library commit or release appropriate for downstream adoption.
• Any necessary changes for the separate RTC integration work.

Do not change Akaunting-specific fiscal persistence, UI or taxpayer-classification logic in this library.

Do not update the consumer dependency before the required library integration has been reviewed.

Acceptance criteria

• The implementation PR includes the complete previous/new official contract matrix.
• Supported contract versions, environments and schema packages are explicitly identified with provenance.
• All implemented NT009 fields and conditional rules are supported by authoritative evidence.
• Generated XML matches the selected officially supported contract, with required ordering and conditions.
• Existing consumer behavior is preserved unless an incompatibility is explicitly documented and approved.
• Annex C and Annex VII remain independently addressable by version.
• No restrictive rule is introduced solely from consultative Annex VIII correlations.
• Deterministic tests cover valid, invalid, optional, conditional and version-transition scenarios.
• Official XSD validation and fixture integrity pass for every contract claimed as supported.
• Downstream migration notes identify the tested version or commit for akaunting-nfse.
• All applicable CI checks pass, and the PR documents any external validation limitations.
• No claim of fiscal conformity or production availability is made without supporting official evidence.

Out of scope

• Reimplementing the annex generation and source monitoring infrastructure.
• Fiscal UI or persistence changes specific to Akaunting.
• Inferring tax classifications or enforcing consultative Annex VIII correlations.
• Automatically changing the production contract whenever a new annex is published.
• NFS-e Via-specific features unrelated to the standard contributor DPS contract.

Official sources

• NT009 / RTC: https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/rtc
• Production documentation: https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual
• Restricted-production documentation: https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/producao-restrita
• Implementation schedule: https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/atualizacoes-e-implantacoes