feat: expand source-backed NT009 DPS review-only groups (#95)

docs/NT009-CONTRACT-IMPLEMENTATION.md

@@ -112,9 +112,40 @@ verified `ind_gIBSCBS` flag is false, and required in the appropriate
 conditional form if it is true.
 
 **The preview deliberately cannot model the complete 450-row new contract.**
-In particular the new `vAjusteBC` structure, detailed `dest` group,
-`gPgtoVinc`, `imovel`, `bensMoveis`, `condominios` and other conditional
-groups are not implemented for production serialization. The builder rejects
+It now includes explicitly typed, separately validated structural drafts for:
+
+- `infDPS/dest` (Annex VI rows 180-200): one identity, optional national or
+  foreign address; identifiers and textual values are validated before
+  insertion, with DOM text nodes used for safe XML escaping.
+- `infDPS/valores/vAjusteBC` (rows 293-336): exactly one ISSQN
+  percentage, monetary or document-backed mode. The document mode accepts
+  up to 1,000 typed `docAjusteBC` entries with a choice of
+  `dFeNacional`, `docFiscalOutro` or `docOutro`, optional dates and
+  explicit `fornec` identity. An optional externally justified
+  `vAjusteBCIBSCBSComExt` may be provided; fiscal applicability is not
+  inferred by the SDK.
+- `IBSCBS/bensMoveis` (rows 404-407): up to 1,000 records, restricted to
+  `cTribNac=99.04.01`, preserving the 8-digit NCM and bounded quantities.
+- `IBSCBS/gPgtoVinc/pgto` (rows 443-449): up to 99 records, with distinct
+  transaction IDs and payment numbers and the published payment method codes.
+- `IBSCBS/imovel` (rows 383-403): explicit municipality, the
+  classification-restricted optional `gLocacao`, and up to 99 units with
+  bounded address and per-unit adjustment data.
+- `IBSCBS/condominios` (rows 408-421): source-coded charge categories and
+  optional detail and discount records, with exact-cent reconciliation of
+  `gDetCobranca` to the charge and total charge values to `vServ`.
+
+The builder now rejects legacy `DpsData::deducaoReducao` in NT009 preview
+instead of silently copying the obsolete `vDedRed` group. This prevents
+mistaking old deduction rules for the new, not-yet-effective schema.
+No taxpayer identity or payment values are inferred.
+
+Still missing are independently confirmed adjustment-type domains
+and tax-code repercussions, externally verified tax-code correlations,
+specialized conditional groups not yet modeled, and — most importantly —
+validation against a published,
+environment-specific **effective NT009 XSD**. None of these review-only
+structures is enabled in the real emission path. The builder rejects
 mixing legacy IBS fields and the new preview options. It removes the obsolete
 `xsi:schemaLocation` reference, without claiming that it matches a new
 schema. The existing `DpsSchemaValidator` remains bound to the February

src/Dto/Nt009AdjustmentDocumentData.php

@@ -0,0 +1,30 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreCodeCoop\NfsePHP\Dto;
+
+/**
+ * One document-backed vAjusteBC entry (Annex VI rows 297-335).
+ * The reference is a discriminated PHP union; no arbitrary XML is accepted.
+ */
+final readonly class Nt009AdjustmentDocumentData
+{
+    public function __construct(
+        /** tpAjusteBC: numeric official type (domain-specific applicability deferred). */
+        public string $tipo,
+        /** vTotDoc, represented as decimal string to avoid float calculations. */
+        public string $valorTotalDocumento,
+        /** vAjusteAplic, represented as decimal string. */
+        public string $valorAjustado,
+        public Nt009NationalInvoiceReference|Nt009OtherFiscalReference|Nt009OtherDocumentReference $referencia,
+        public ?string $descricaoTipo = null,
+        public ?string $dataEmissao = null,
+        public ?string $dataCompetencia = null,
+        public ?Nt009RecipientData $fornecedor = null,
+    ) {
+    }
+}

src/Dto/Nt009BaseAdjustmentData.php

@@ -0,0 +1,30 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreCodeCoop\NfsePHP\Dto;
+
+/**
+ * Review-only NT009 valores/vAjusteBC. Monetary, percentage and explicit
+ * document-backed alternatives are mutually exclusive and never inferred.
+ */
+final readonly class Nt009BaseAdjustmentData
+{
+    /**
+     * @param list<Nt009AdjustmentDocumentData> $documentos
+     */
+    public function __construct(
+        /** pAjusteBCISSQN, mutually exclusive with valorIssqn. */
+        public ?string $percentualIssqn = null,
+        /** vAjusteBCISSQN, mutually exclusive with percentualIssqn. */
+        public ?string $valorIssqn = null,
+        /** vAjusteBCIBSCBSComExt, only when separately applicable. */
+        public ?string $valorIbsCbsComExterior = null,
+        /** Document-based alternative to percentage or monetary adjustment. */
+        public array $documentos = [],
+    ) {
+    }
+}

src/Dto/Nt009CondominiumChargeData.php

@@ -0,0 +1,23 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreCodeCoop\NfsePHP\Dto;
+
+/** Draft-only gCobranca for a condominium, Annex VI rows 410-417. */
+final readonly class Nt009CondominiumChargeData
+{
+    /**
+     * @param list<Nt009CondominiumDetailData> $detalhes
+     */
+    public function __construct(
+        public string $tipo,
+        public string $valor,
+        public ?string $descricaoTipo = null,
+        public array $detalhes = [],
+    ) {
+    }
+}

src/Dto/Nt009CondominiumData.php

@@ -0,0 +1,23 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreCodeCoop\NfsePHP\Dto;
+
+/** Draft-only condominium group; source Annex VI 408-421. */
+final readonly class Nt009CondominiumData
+{
+    /**
+     * @param list<Nt009CondominiumChargeData> $cobrancas
+     * @param list<Nt009CondominiumDiscountData> $descontos
+     */
+    public function __construct(
+        public string $vencimentoOriginal,
+        public array $cobrancas,
+        public array $descontos = [],
+    ) {
+    }
+}

src/Dto/Nt009CondominiumDetailData.php

@@ -0,0 +1,19 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreCodeCoop\NfsePHP\Dto;
+
+/** Draft-only optional gDetCobranca breakdown. */
+final readonly class Nt009CondominiumDetailData
+{
+    public function __construct(
+        public string $tipo,
+        public string $valor,
+        public ?string $descricaoTipo = null,
+    ) {
+    }
+}

src/Dto/Nt009CondominiumDiscountData.php

@@ -0,0 +1,19 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreCodeCoop\NfsePHP\Dto;
+
+/** Draft-only gDesconto for a condominium. */
+final readonly class Nt009CondominiumDiscountData
+{
+    public function __construct(
+        public string $tipo,
+        public string $valor,
+        public string $descricaoTipo,
+    ) {
+    }
+}

src/Dto/Nt009DpsPreviewData.php

@@ -16,6 +16,10 @@
  */
 final readonly class Nt009DpsPreviewData
 {
+    /**
+     * @param list<Nt009LinkedPaymentData> $pagamentosVinculados
+     * @param list<Nt009MovableAssetData> $bensMoveis
+     */
     public function __construct(
         /** finNFSe: 0 regular, 1 credit, 2 debit. */
         public int $finalidade,
@@ -43,6 +47,18 @@ public function __construct(
         public ?string $valorAjusteCbs = null,
         /** regApIBSCBSSN 1, 2 or 3, when applicable. */
         public ?int $regimeApuracaoSimples = null,
+        /** Recipient identity is required when indDest=1. */
+        public ?Nt009RecipientData $destinatario = null,
+        /** Explicit new base-adjustment form; never repurpose legacy vDedRed. */
+        public ?Nt009BaseAdjustmentData $ajusteBase = null,
+        /** Up to 1000 movable-rental items for cTribNac 99.04.01. */
+        public array $bensMoveis = [],
+        /** Up to 99 transaction records under IBSCBS/gPgtoVinc. */
+        public array $pagamentosVinculados = [],
+        /** Optional property operation details, Annex VI rows 383-403. */
+        public ?Nt009RealEstateData $imovel = null,
+        /** Optional condominium billing, Annex VI rows 408-421. */
+        public ?Nt009CondominiumData $condominios = null,
     ) {
     }
 }

src/Dto/Nt009LeaseData.php

@@ -0,0 +1,21 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreCodeCoop\NfsePHP\Dto;
+
+/** Draft-only property lease group gLocacao. */
+final readonly class Nt009LeaseData
+{
+    public function __construct(
+        public string $percentualCopropriedade,
+        public string $valorTotalOperacao,
+        public ?string $descontoIncondicional = null,
+        public ?string $descontoCondicional = null,
+        public ?string $dataVencimentoOriginal = null,
+    ) {
+    }
+}

src/Dto/Nt009LinkedPaymentData.php

@@ -0,0 +1,28 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreCodeCoop\NfsePHP\Dto;
+
+/**
+ * One entry of IBSCBS/gPgtoVinc/pgto, as published in Annex VI v1.04.01.
+ */
+final readonly class Nt009LinkedPaymentData
+{
+    public function __construct(
+        /** nPag: unique 1-3 digit payment number. */
+        public string $numeroPagamento,
+        /** idTransacao: unique 2-35 character financial transaction identifier. */
+        public string $identificadorTransacao,
+        /** tpMeioPgto: published means of payment, e.g. 17 (dynamic PIX). */
+        public string $tipoMeioPagamento,
+        /** CNPJReceb: 14-character recipient CNPJ, potentially alphanumeric. */
+        public string $cnpjRecebedor,
+        /** CNPJBasePSP: 8-character base of the payment service provider CNPJ. */
+        public string $cnpjBasePsp,
+    ) {
+    }
+}

src/Dto/Nt009MovableAssetData.php

@@ -0,0 +1,24 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreCodeCoop\NfsePHP\Dto;
+
+/**
+ * One rental movable asset: IBSCBS/bensMoveis, only for cTribNac 99.04.01.
+ */
+final readonly class Nt009MovableAssetData
+{
+    public function __construct(
+        /** cNCMBemMovel: NCM with exactly 8 digits. */
+        public string $ncm,
+        /** xNCMBemMovel: human-readable name (1-150 chars). */
+        public string $descricao,
+        /** qtdNCMBemMovel: positive whole quantity, at most three digits. */
+        public int $quantidade,
+    ) {
+    }
+}

src/Dto/Nt009NationalInvoiceReference.php

@@ -0,0 +1,19 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreCodeCoop\NfsePHP\Dto;
+
+/** Choice dFeNacional inside a document-based base adjustment. */
+final readonly class Nt009NationalInvoiceReference
+{
+    public function __construct(
+        public string $tipoChaveDfe,
+        public string $chaveDfe,
+        public ?string $descricaoTipoChaveDfe = null,
+    ) {
+    }
+}

src/Dto/Nt009OtherDocumentReference.php

@@ -0,0 +1,18 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreCodeCoop\NfsePHP\Dto;
+
+/** Choice docOutro inside a document-based base adjustment. */
+final readonly class Nt009OtherDocumentReference
+{
+    public function __construct(
+        public string $numero,
+        public string $descricao,
+    ) {
+    }
+}

src/Dto/Nt009OtherFiscalReference.php

@@ -0,0 +1,19 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreCodeCoop\NfsePHP\Dto;
+
+/** Choice docFiscalOutro inside a document-based base adjustment. */
+final readonly class Nt009OtherFiscalReference
+{
+    public function __construct(
+        public string $municipioIbge,
+        public string $numeroDocumento,
+        public string $descricaoDocumento,
+    ) {
+    }
+}

src/Dto/Nt009PropertyAdjustmentData.php

@@ -0,0 +1,19 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreCodeCoop\NfsePHP\Dto;
+
+/** Draft-only gAjusteBCLocImoveis entry for one property unit. */
+final readonly class Nt009PropertyAdjustmentData
+{
+    public function __construct(
+        public string $tipo,
+        public string $valor,
+        public ?string $descricaoTipo = null,
+    ) {
+    }
+}