[vitormattos]

Issue #95 — NT009 v1.01, source-verified implementation and unresolved deployment gate

Review scope: versioned offline domain access, full normative field-diff evidence, a strictly opt-in non-emitting structural preview, and reproducible official XSD package comparison. This PR does not close #95 and does not activate an unsupported production or restricted-production emitter.

Completed and directly verified

• OfficialDomainCatalog::operationIndicator($code, $version) and hasOperationIndicator($code, $version) support explicit Annex C v1.01 (26 codes) or Annex VII v1.03.00 (40 codes). The original one-argument default and existing behavior are unchanged. All 40 exact triplets remain from PRs refactor: replace Python domain utilities with isolated PHP tooling #97/feat: audit official NT009 indicators and layout evidence in PHP (#95) #99.
• Added a deterministic 450-row matrix at resources/contracts/nt009-dps-v1.04.01-matrix.tsv: every included XML path, original/new source row, kind, datatype, cardinality, length, description and condition, from checksum-pinned official Anexo I (production, 2026-02-09) and Anexo VI (NT009). Counts: 168 unchanged, 38 modified, 135 added, 109 removed/moved. composer domains:contract-matrix recreates the complete file, checked byte-for-byte by the NT009 CI job.
• Added XmlBuilder::previewNt009Dps(DpsData, Nt009DpsPreviewData): Nt009DpsPreview, an explicitly non-emitting typed preview, leaving XmlBuilder::buildDps(), the DpsData constructor, NfseClient::emit() and the old production DpsSchemaValidator untouched.
• The preview models normative placement and basic conditionality of finNFSe, tpNFSeDebito, tpNFSeCredito, indDest, regApIBSCBSSN, IBSCBS/indFinal, cIndOp, CST, cClassTrib, gIBSCBS and gIBSCBSAjuste, with externally verified ind_gIBSCBS. PHPUnit proves old output unchanged, structural paths, omissions, invalid combinations, official Annex VII code lookup and the rejection of NT009 preview XML by the old production XSD. No restrictive correlation is inferred from consultative Annex VIII.
• The first-party PHP CLI and PHPUnit tools compare both official v1.01 XSD ZIP packages, pinning the URL and observed SHA-256 in resources/domains/sources.json:
  • Production 20260209: e7935cbd9470527c6cc32984c1b2263e614183bf0139ce2733eaaed2de9a8072
  • Restricted production 20260727: 6c7e0510d3ecff4454f291f4e10b742d27a4818f23aab181494f96d0ea79f3dc
  • Comparing uncompressed XSD bytes by basename, 10 common basenames contain different bytes and 7 occur only in the production bundle. The numeric version alone does not establish equivalence.
• docs/NT009-CONTRACT-IMPLEMENTATION.md contains source provenance, representative hierarchy diffs, reproducibility instructions, explicit preview API and migration boundaries. It identifies akaunting-nfse's existing pin dev-main#f179d7f723bec80f5b19a25dfbc385a612c2447f, its RuntimeDpsFactory, InvoiceDpsBuilder and IssueInvoiceNfse, and why the consumer must not be updated before a validated new emitting contract exists.
• 18 incremental commits, each Git Signing MCP-signed and DCO-compliant, without squash or merge.

Critical unresolved official blockers

1. The RTC portal currently publishes the NT009 v1.01 PDF, Anexo VI v1.04.01 and Anexo VII v1.03.00, but does not identify an NT009-specific official XSD package as deployed in production or restricted production, or publish its effective-date schedule. A published spreadsheet is not a production-ready XML schema.
2. The NT009 PDF §2.2 places gIBSCBSAjuste directly beneath trib, whereas the newer Anexo VI v1.04.01 worksheet places it under trib/gIBSCBS (source row 428). The preview follows the worksheet only for review; this conflict requires authoritative XSD clarification.
3. The preview covers some source-verified fields but not the entire revised DPS contract, including new vAjusteBC, recipient dest, gPgtoVinc, imovel, bensMoveis, condominios and other complex conditional groups. It cannot be used for issuance. An accepted official XSD and correct applicable environment are prerequisites to an approved versioned emission API.
4. Authoritative CST/cClassTrib applicability and ind_gIBSCBS rules must be verified independently, without enforcing advisory Annex VIII.
5. Only after external normative prerequisites and full XSD/SEFIN validation should the downstream module pin a reviewed merged commit/release and add RTC integration.

See government RTC: https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/rtc , production: https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual , restricted: https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/producao-restrita .

CI & review

PHPUnit, Psalm, PHP CS Fixer, minimum dependency gates, REUSE, offline domain-tool tests, 5 production TSV snapshots, complete 40-indicator comparison and the entire 450-row normative matrix have passed on this feature branch. The actual official XSD ZIP comparison job has also passed after baselining and fixing duplicate filenames in distinct directory trees. Confirm all checks on the latest commit before approving.

Do not merge without the maintainer's explicit authorization. Do not close issue #95 or claim fiscal conformity.