@fin.cx/einvoice 9.0.0 → 10.0.0

package/ts/formats/validation/vat-categories.validator.ts

@@ -1,9 +1,15 @@
-import * as plugins from '../../plugins.js';
-import { findInvalidItemAmounts, getTotalsSkippedResult } from '../utils/document.totals.js';
+import {
+  computeDocumentTotals,
+  findInvalidItemAmounts,
+  getDocumentCalculator,
+  getTotalsSkippedResult,
+  type IDocumentTotals,
+} from '../utils/document.totals.js';
 import type { TAccountingDocItem } from '@tsclass/tsclass/dist_ts/finance/index.js';
 import type { EInvoice } from '../../einvoice.js';
-import { CurrencyCalculator } from '../utils/currency.utils.js';
-import { isEuMemberState } from '../utils/eu.memberstates.js';
+import type { DecimalCurrencyCalculator } from '../utils/currency.calculator.decimal.js';
+import { Decimal } from '../utils/decimal.js';
+import type { TVatCategoryCode } from '../utils/vat.category.js';
 import type { ValidationResult } from './validation.types.js';
 
 /**
@@ -34,24 +40,75 @@ export interface VATBreakdown {
 }
 
 /**
- * Comprehensive VAT Category Rules Validator
- * Implements all EN16931 VAT category-specific business rules
+ * The EN 16931 rules this validator checks, with their official text (CEN/TC 434
+ * EN 16931 validation artefacts 1.3.16, the UBL model; the CII model differs only
+ * in the case of "Breakdown" in BR-AE-10 and BR-S-10 and "VAT breakdown" in BR-AE-01)
+ */
+const VAT_CATEGORY_RULES = {
+  'BR-S-01':
+    'An Invoice that contains an Invoice line (BG-25), a Document level allowance (BG-20) or a Document level charge (BG-21) where the VAT category code (BT-151, BT-95 or BT-102) is "Standard rated" shall contain in the VAT breakdown (BG-23) at least one VAT category code (BT-118) equal with "Standard rated".',
+  'BR-S-05':
+    'In an Invoice line (BG-25) where the Invoiced item VAT category code (BT-151) is "Standard rated" the Invoiced item VAT rate (BT-152) shall be greater than zero.',
+  'BR-S-08':
+    'For each different value of VAT category rate (BT-119) where the VAT category code (BT-118) is "Standard rated", the VAT category taxable amount (BT-116) in a VAT breakdown (BG-23) shall equal the sum of Invoice line net amounts (BT-131) plus the sum of document level charge amounts (BT-99) minus the sum of document level allowance amounts (BT-92) where the VAT category code (BT-151, BT-102, BT-95) is "Standard rated" and the VAT rate (BT-152, BT-103, BT-96) equals the VAT category rate (BT-119).',
+  'BR-S-09':
+    'The VAT category tax amount (BT-117) in a VAT breakdown (BG-23) where VAT category code (BT-118) is "Standard rated" shall equal the VAT category taxable amount (BT-116) multiplied by the VAT category rate (BT-119).',
+  'BR-S-10':
+    'A VAT breakdown (BG-23) with VAT Category code (BT-118) "Standard rate" shall not have a VAT exemption reason code (BT-121) or VAT exemption reason text (BT-120).',
+  'BR-AE-01':
+    'An Invoice that contains an Invoice line (BG-25), a Document level allowance (BG-20) or a Document level charge (BG-21) where the VAT category code (BT-151, BT-95 or BT-102) is "Reverse charge" shall contain in the VAT Breakdown (BG-23) exactly one VAT category code (BT-118) equal with "VAT reverse charge".',
+  'BR-AE-02':
+    'An Invoice that contains an Invoice line (BG-25) where the Invoiced item VAT category code (BT-151) is "Reverse charge" shall contain the Seller VAT Identifier (BT-31), the Seller Tax registration identifier (BT-32) and/or the Seller tax representative VAT identifier (BT-63) and the Buyer VAT identifier (BT-48) and/or the Buyer legal registration identifier (BT-47).',
+  'BR-AE-05':
+    'In an Invoice line (BG-25) where the Invoiced item VAT category code (BT-151) is "Reverse charge" the Invoiced item VAT rate (BT-152) shall be 0 (zero).',
+  'BR-AE-08':
+    'In a VAT breakdown (BG-23) where the VAT category code (BT-118) is "Reverse charge" the VAT category taxable amount (BT-116) shall equal the sum of Invoice line net amounts (BT-131) minus the sum of Document level allowance amounts (BT-92) plus the sum of Document level charge amounts (BT-99) where the VAT category codes (BT-151, BT-95, BT-102) are "Reverse charge".',
+  'BR-AE-09':
+    'The VAT category tax amount (BT-117) in a VAT breakdown (BG-23) where the VAT category code (BT-118) is "Reverse charge" shall be 0 (zero).',
+  'BR-AE-10':
+    'A VAT breakdown (BG-23) with VAT Category code (BT-118) "Reverse charge" shall have a VAT exemption reason code (BT-121), meaning "Reverse charge" or the VAT exemption reason text (BT-120) "Reverse charge" (or the equivalent standard text in another language).',
+  'BR-CO-17':
+    'VAT category tax amount (BT-117) = VAT category taxable amount (BT-116) x (VAT category rate (BT-119) / 100), rounded to two decimals.',
+} as const;
+
+type TVatCategoryRuleId = keyof typeof VAT_CATEGORY_RULES;
+
+/** The finding of one rule: where it applies and, for an amount, the value found and expected */
+interface IVatCategoryFinding {
+  field: string;
+  btReference: string;
+  bgReference?: string;
+  value?: unknown;
+  expected?: unknown;
+  remediation?: string;
+}
+
+/**
+ * The EN 16931 VAT category rules of a document, checked on the VAT categories
+ * and the VAT breakdown the encoders write.
+ *
+ * The category of every line is the one the encoders write (`getVatCategory`):
+ * reverse charge (AE) when the document states `reverseCharge`, standard rated
+ * (S) otherwise. The envelope states no category of its own for an item or a
+ * breakdown, so the other categories (Z, E, K, G, O, L, M) cannot occur, and
+ * an item's `metadata` is not read for one. A decoded document may state one
+ * for a line (`statedValues.lines[].vatCategoryCode`); the envelope reads such
+ * a line as S, so BR-S-05 is not reported for a line whose stated category is
+ * not S. The VAT breakdown is the one the
+ * encoders write (`computeDocumentTotals().vatGroups`): one group per category
+ * and rate. The envelope has no document level allowances or charges, so the
+ * rules on them (BR-S-02 to -04 and -06 to -07 and their counterparts) do not
+ * apply, and a taxable amount is the sum of the line net amounts.
  */
 export class VATCategoriesValidator {
   private results: ValidationResult[] = [];
-  private currencyCalculator?: CurrencyCalculator;
-  
+
   /**
    * Validate VAT categories according to EN16931
    */
   public validate(invoice: EInvoice): ValidationResult[] {
     this.results = [];
-    
-    // Initialize currency calculator if currency is available
-    if (invoice.currency) {
-      this.currencyCalculator = new CurrencyCalculator(invoice.currency);
-    }
-    
+
     // The VAT breakdown is computed from the line amounts; while one is no number it cannot
     // be, so these rules are skipped and the result says so (the line rules report the lines)
     const invalidAmounts = findInvalidItemAmounts(invoice.items);
@@ -60,774 +117,135 @@ export class VATCategoriesValidator {
       return this.results;
     }
 
-    // Group items by VAT category
-    const itemsByCategory = this.groupItemsByVATCategory(invoice.items || []);
-    const breakdownsByCategory = this.groupBreakdownsByCategory(invoice.taxBreakdown || []);
-    
-    // Validate each VAT category
-    this.validateStandardRate(itemsByCategory.get('S'), breakdownsByCategory.get('S'), invoice);
-    this.validateZeroRated(itemsByCategory.get('Z'), breakdownsByCategory.get('Z'), invoice);
-    this.validateExempt(itemsByCategory.get('E'), breakdownsByCategory.get('E'), invoice);
-    this.validateReverseCharge(itemsByCategory.get('AE'), breakdownsByCategory.get('AE'), invoice);
-    this.validateIntraCommunity(itemsByCategory.get('K'), breakdownsByCategory.get('K'), invoice);
-    this.validateExport(itemsByCategory.get('G'), breakdownsByCategory.get('G'), invoice);
-    this.validateOutOfScope(itemsByCategory.get('O'), breakdownsByCategory.get('O'), invoice);
-    
-    // Cross-category validation
-    this.validateCrossCategoryRules(invoice, itemsByCategory, breakdownsByCategory);
-    
+    const totals = computeDocumentTotals(invoice);
+    const calculator = getDocumentCalculator(invoice.currency);
+    const items = invoice.items ?? [];
+
+    this.validateLines(invoice, items, totals);
+    this.validateBreakdown(items, totals, calculator);
     return this.results;
   }
-  
-  /**
-   * Validate Standard Rate VAT (BR-S-*)
-   */
-  private validateStandardRate(
-    items?: TAccountingDocItem[],
-    breakdown?: any,
-    invoice?: EInvoice
-  ): void {
-    if (!items || items.length === 0) return;
-    
-    // BR-S-01: Invoice with standard rated items must have standard rated breakdown
-    if (!breakdown) {
-      this.addError('BR-S-01', 
-        'Invoice with standard rated items must have a standard rated VAT breakdown',
-        'taxBreakdown'
-      );
-      return;
-    }
-    
-    // BR-S-02: Standard rate VAT category taxable amount
-    const expectedTaxable = this.calculateTaxableAmount(items);
-    if (!this.areAmountsEqual(breakdown.netAmount, expectedTaxable)) {
-      this.addError('BR-S-02',
-        `Standard rate VAT taxable amount mismatch`,
-        'taxBreakdown.netAmount',
-        breakdown.netAmount,
-        expectedTaxable
-      );
-    }
-    
-    // BR-S-03: Standard rate VAT category tax amount
-    const rate = breakdown.taxPercent || 0;
-    const expectedTax = this.calculateVATAmount(expectedTaxable, rate);
-    if (!this.areAmountsEqual(breakdown.taxAmount, expectedTax)) {
-      this.addError('BR-S-03',
-        `Standard rate VAT tax amount mismatch`,
-        'taxBreakdown.taxAmount',
-        breakdown.taxAmount,
-        expectedTax
-      );
-    }
-    
-    // BR-S-04: Standard rate VAT category code must be "S"
-    if (breakdown.categoryCode && breakdown.categoryCode !== 'S') {
-      this.addError('BR-S-04',
-        'Standard rate VAT category code must be "S"',
-        'taxBreakdown.categoryCode',
-        breakdown.categoryCode,
-        'S'
-      );
-    }
-    
-    // BR-S-05: Standard rate VAT rate must be greater than zero
-    if (rate <= 0) {
-      this.addError('BR-S-05',
-        'Standard rate VAT rate must be greater than zero',
-        'taxBreakdown.taxPercent',
-        rate,
-        '> 0'
-      );
-    }
-    
-    // BR-S-08: No exemption reason for standard rate
-    if (breakdown.exemptionReason) {
-      this.addError('BR-S-08',
-        'Standard rate VAT must not have an exemption reason',
-        'taxBreakdown.exemptionReason'
-      );
-    }
-  }
-  
-  /**
-   * Validate Zero Rated VAT (BR-Z-*)
-   */
-  private validateZeroRated(
-    items?: TAccountingDocItem[],
-    breakdown?: any,
-    invoice?: EInvoice
-  ): void {
-    if (!items || items.length === 0) return;
-    
-    // BR-Z-01: Invoice with zero rated items must have zero rated breakdown
-    if (!breakdown) {
-      this.addError('BR-Z-01',
-        'Invoice with zero rated items must have a zero rated VAT breakdown',
-        'taxBreakdown'
-      );
-      return;
-    }
-    
-    // BR-Z-02: Zero rate VAT category taxable amount
-    const expectedTaxable = this.calculateTaxableAmount(items);
-    if (!this.areAmountsEqual(breakdown.netAmount, expectedTaxable)) {
-      this.addError('BR-Z-02',
-        'Zero rate VAT taxable amount mismatch',
-        'taxBreakdown.netAmount',
-        breakdown.netAmount,
-        expectedTaxable
-      );
-    }
-    
-    // BR-Z-03: Zero rate VAT tax amount must be zero
-    if (breakdown.taxAmount !== 0) {
-      this.addError('BR-Z-03',
-        'Zero rate VAT tax amount must be zero',
-        'taxBreakdown.taxAmount',
-        breakdown.taxAmount,
-        0
-      );
-    }
-    
-    // BR-Z-04: Zero rate VAT category code must be "Z"
-    if (breakdown.categoryCode && breakdown.categoryCode !== 'Z') {
-      this.addError('BR-Z-04',
-        'Zero rate VAT category code must be "Z"',
-        'taxBreakdown.categoryCode',
-        breakdown.categoryCode,
-        'Z'
-      );
-    }
-    
-    // BR-Z-05: Zero rate VAT rate must be zero
-    if (breakdown.taxPercent !== 0) {
-      this.addError('BR-Z-05',
-        'Zero rate VAT rate must be zero',
-        'taxBreakdown.taxPercent',
-        breakdown.taxPercent,
-        0
-      );
-    }
-  }
-  
-  /**
-   * Validate Exempt from Tax (BR-E-*)
-   */
-  private validateExempt(
-    items?: TAccountingDocItem[],
-    breakdown?: any,
-    invoice?: EInvoice
-  ): void {
-    if (!items || items.length === 0) return;
-    
-    // BR-E-01: Invoice with exempt items must have exempt breakdown
-    if (!breakdown) {
-      this.addError('BR-E-01',
-        'Invoice with tax exempt items must have an exempt VAT breakdown',
-        'taxBreakdown'
-      );
-      return;
-    }
-    
-    // BR-E-02: Exempt VAT category taxable amount
-    const expectedTaxable = this.calculateTaxableAmount(items);
-    if (!this.areAmountsEqual(breakdown.netAmount, expectedTaxable)) {
-      this.addError('BR-E-02',
-        'Exempt VAT taxable amount mismatch',
-        'taxBreakdown.netAmount',
-        breakdown.netAmount,
-        expectedTaxable
-      );
-    }
-    
-    // BR-E-03: Exempt VAT tax amount must be zero
-    if (breakdown.taxAmount !== 0) {
-      this.addError('BR-E-03',
-        'Exempt VAT tax amount must be zero',
-        'taxBreakdown.taxAmount',
-        breakdown.taxAmount,
-        0
-      );
-    }
-    
-    // BR-E-04: Exempt VAT category code must be "E"
-    if (breakdown.categoryCode && breakdown.categoryCode !== 'E') {
-      this.addError('BR-E-04',
-        'Exempt VAT category code must be "E"',
-        'taxBreakdown.categoryCode',
-        breakdown.categoryCode,
-        'E'
-      );
-    }
-    
-    // BR-E-05: Exempt VAT rate must be zero
-    if (breakdown.taxPercent !== 0) {
-      this.addError('BR-E-05',
-        'Exempt VAT rate must be zero',
-        'taxBreakdown.taxPercent',
-        breakdown.taxPercent,
-        0
-      );
-    }
-    
-    // BR-E-06: Exempt VAT must have exemption reason
-    if (!breakdown.exemptionReason && !breakdown.exemptionReasonCode) {
-      this.addError('BR-E-06',
-        'Exempt VAT must have an exemption reason or exemption reason code',
-        'taxBreakdown.exemptionReason'
-      );
-    }
-  }
-  
-  /**
-   * Validate VAT Reverse Charge (BR-AE-*)
-   */
-  private validateReverseCharge(
-    items?: TAccountingDocItem[],
-    breakdown?: any,
-    invoice?: EInvoice
-  ): void {
-    if (!items || items.length === 0) return;
-    
-    // BR-AE-01: Invoice with reverse charge items must have reverse charge breakdown
-    if (!breakdown) {
-      this.addError('BR-AE-01',
-        'Invoice with reverse charge items must have a reverse charge VAT breakdown',
-        'taxBreakdown'
-      );
-      return;
-    }
-    
-    // BR-AE-02: Reverse charge VAT category taxable amount
-    const expectedTaxable = this.calculateTaxableAmount(items);
-    if (!this.areAmountsEqual(breakdown.netAmount, expectedTaxable)) {
-      this.addError('BR-AE-02',
-        'Reverse charge VAT taxable amount mismatch',
-        'taxBreakdown.netAmount',
-        breakdown.netAmount,
-        expectedTaxable
-      );
-    }
-    
-    // BR-AE-03: Reverse charge VAT tax amount must be zero
-    if (breakdown.taxAmount !== 0) {
-      this.addError('BR-AE-03',
-        'Reverse charge VAT tax amount must be zero',
-        'taxBreakdown.taxAmount',
-        breakdown.taxAmount,
-        0
-      );
-    }
-    
-    // BR-AE-04: Reverse charge VAT category code must be "AE"
-    if (breakdown.categoryCode && breakdown.categoryCode !== 'AE') {
-      this.addError('BR-AE-04',
-        'Reverse charge VAT category code must be "AE"',
-        'taxBreakdown.categoryCode',
-        breakdown.categoryCode,
-        'AE'
-      );
-    }
-    
-    // BR-AE-05: Reverse charge VAT rate must be zero
-    if (breakdown.taxPercent !== 0) {
-      this.addError('BR-AE-05',
-        'Reverse charge VAT rate must be zero',
-        'taxBreakdown.taxPercent',
-        breakdown.taxPercent,
-        0
-      );
-    }
-    
-    // BR-AE-06: Reverse charge must have exemption reason
-    if (!breakdown.exemptionReason && !breakdown.exemptionReasonCode) {
-      this.addError('BR-AE-06',
-        'Reverse charge VAT must have an exemption reason',
-        'taxBreakdown.exemptionReason'
-      );
-    }
-    
-    // BR-AE-08: Buyer must have VAT identifier for reverse charge
-    if (!invoice?.metadata?.buyerTaxId) {
-      this.addError('BR-AE-08',
-        'Buyer must have a VAT identifier for reverse charge invoices',
-        'metadata.buyerTaxId'
-      );
-    }
-  }
-  
-  /**
-   * Validate Intra-Community Supply (BR-K-*)
-   */
-  private validateIntraCommunity(
-    items?: TAccountingDocItem[],
-    breakdown?: any,
-    invoice?: EInvoice
-  ): void {
-    if (!items || items.length === 0) return;
-    
-    // BR-K-01: Invoice with intra-community items must have intra-community breakdown
-    if (!breakdown) {
-      this.addError('BR-K-01',
-        'Invoice with intra-community supply must have corresponding VAT breakdown',
-        'taxBreakdown'
-      );
-      return;
-    }
-    
-    // BR-K-02: Intra-community VAT category taxable amount
-    const expectedTaxable = this.calculateTaxableAmount(items);
-    if (!this.areAmountsEqual(breakdown.netAmount, expectedTaxable)) {
-      this.addError('BR-K-02',
-        'Intra-community VAT taxable amount mismatch',
-        'taxBreakdown.netAmount',
-        breakdown.netAmount,
-        expectedTaxable
-      );
-    }
-    
-    // BR-K-03: Intra-community VAT tax amount must be zero
-    if (breakdown.taxAmount !== 0) {
-      this.addError('BR-K-03',
-        'Intra-community VAT tax amount must be zero',
-        'taxBreakdown.taxAmount',
-        breakdown.taxAmount,
-        0
-      );
-    }
-    
-    // BR-K-04: Intra-community VAT category code must be "K"
-    if (breakdown.categoryCode && breakdown.categoryCode !== 'K') {
-      this.addError('BR-K-04',
-        'Intra-community VAT category code must be "K"',
-        'taxBreakdown.categoryCode',
-        breakdown.categoryCode,
-        'K'
-      );
-    }
-    
-    // BR-K-05: Intra-community VAT rate must be zero
-    if (breakdown.taxPercent !== 0) {
-      this.addError('BR-K-05',
-        'Intra-community VAT rate must be zero',
-        'taxBreakdown.taxPercent',
-        breakdown.taxPercent,
-        0
-      );
-    }
-    
-    // BR-K-06: Must have exemption reason
-    if (!breakdown.exemptionReason && !breakdown.exemptionReasonCode) {
-      this.addError('BR-K-06',
-        'Intra-community supply must have an exemption reason',
-        'taxBreakdown.exemptionReason'
-      );
-    }
-    
-    // BR-K-08: Both seller and buyer must have VAT identifiers
-    if (!invoice?.metadata?.sellerTaxId) {
-      this.addError('BR-K-08',
-        'Seller must have a VAT identifier for intra-community supply',
-        'metadata.sellerTaxId'
-      );
-    }
-    
-    if (!invoice?.metadata?.buyerTaxId) {
-      this.addError('BR-K-09',
-        'Buyer must have a VAT identifier for intra-community supply',
-        'metadata.buyerTaxId'
-      );
-    }
-    
-    // BR-K-10: Must be in different EU member states
-    if (invoice?.from?.address?.countryCode === invoice?.to?.address?.countryCode) {
-      this.addWarning('BR-K-10',
-        'Intra-community supply should be between different EU member states',
-        'address.countryCode'
-      );
-    }
-  }
-  
-  /**
-   * Validate Export Outside EU (BR-G-*)
-   */
-  private validateExport(
-    items?: TAccountingDocItem[],
-    breakdown?: any,
-    invoice?: EInvoice
-  ): void {
-    if (!items || items.length === 0) return;
-    
-    // BR-G-01: Invoice with export items must have export breakdown
-    if (!breakdown) {
-      this.addError('BR-G-01',
-        'Invoice with export items must have an export VAT breakdown',
-        'taxBreakdown'
-      );
-      return;
-    }
-    
-    // BR-G-02: Export VAT category taxable amount
-    const expectedTaxable = this.calculateTaxableAmount(items);
-    if (!this.areAmountsEqual(breakdown.netAmount, expectedTaxable)) {
-      this.addError('BR-G-02',
-        'Export VAT taxable amount mismatch',
-        'taxBreakdown.netAmount',
-        breakdown.netAmount,
-        expectedTaxable
-      );
-    }
-    
-    // BR-G-03: Export VAT tax amount must be zero
-    if (breakdown.taxAmount !== 0) {
-      this.addError('BR-G-03',
-        'Export VAT tax amount must be zero',
-        'taxBreakdown.taxAmount',
-        breakdown.taxAmount,
-        0
-      );
-    }
-    
-    // BR-G-04: Export VAT category code must be "G"
-    if (breakdown.categoryCode && breakdown.categoryCode !== 'G') {
-      this.addError('BR-G-04',
-        'Export VAT category code must be "G"',
-        'taxBreakdown.categoryCode',
-        breakdown.categoryCode,
-        'G'
-      );
-    }
-    
-    // BR-G-05: Export VAT rate must be zero
-    if (breakdown.taxPercent !== 0) {
-      this.addError('BR-G-05',
-        'Export VAT rate must be zero',
-        'taxBreakdown.taxPercent',
-        breakdown.taxPercent,
-        0
-      );
-    }
-    
-    // BR-G-06: Must have exemption reason
-    if (!breakdown.exemptionReason && !breakdown.exemptionReasonCode) {
-      this.addError('BR-G-06',
-        'Export must have an exemption reason',
-        'taxBreakdown.exemptionReason'
-      );
-    }
-    
-    // BR-G-08: Buyer should be outside EU
-    const buyerCountry = invoice?.to?.address?.countryCode;
-    if (buyerCountry && this.isEUCountry(buyerCountry)) {
-      this.addWarning('BR-G-08',
-        'Export category should be used for buyers outside EU',
-        'to.address.countryCode',
-        buyerCountry,
-        'non-EU'
-      );
-    }
-  }
-  
+
   /**
-   * Validate Out of Scope Services (BR-O-*)
+   * The rules on the lines of each category: the rate (BR-S-05, BR-AE-05), the breakdown the
+   * category needs (BR-S-01, BR-AE-01) and the parties' identifiers of reverse charge (BR-AE-02)
    */
-  private validateOutOfScope(
-    items?: TAccountingDocItem[],
-    breakdown?: any,
-    invoice?: EInvoice
-  ): void {
-    if (!items || items.length === 0) return;
-    
-    // BR-O-01: Invoice with out of scope items must have out of scope breakdown
-    if (!breakdown) {
-      this.addError('BR-O-01',
-        'Invoice with out of scope items must have corresponding VAT breakdown',
-        'taxBreakdown'
-      );
-      return;
-    }
-    
-    // BR-O-02: Out of scope VAT category taxable amount
-    const expectedTaxable = this.calculateTaxableAmount(items);
-    if (!this.areAmountsEqual(breakdown.netAmount, expectedTaxable)) {
-      this.addError('BR-O-02',
-        'Out of scope VAT taxable amount mismatch',
-        'taxBreakdown.netAmount',
-        breakdown.netAmount,
-        expectedTaxable
-      );
-    }
-    
-    // BR-O-03: Out of scope VAT tax amount must be zero
-    if (breakdown.taxAmount !== 0) {
-      this.addError('BR-O-03',
-        'Out of scope VAT tax amount must be zero',
-        'taxBreakdown.taxAmount',
-        breakdown.taxAmount,
-        0
-      );
-    }
-    
-    // BR-O-04: Out of scope VAT category code must be "O"
-    if (breakdown.categoryCode && breakdown.categoryCode !== 'O') {
-      this.addError('BR-O-04',
-        'Out of scope VAT category code must be "O"',
-        'taxBreakdown.categoryCode',
-        breakdown.categoryCode,
-        'O'
-      );
-    }
-    
-    // BR-O-05: Out of scope VAT rate must be zero
-    if (breakdown.taxPercent !== 0) {
-      this.addError('BR-O-05',
-        'Out of scope VAT rate must be zero',
-        'taxBreakdown.taxPercent',
-        breakdown.taxPercent,
-        0
-      );
+  private validateLines(invoice: EInvoice, items: TAccountingDocItem[], totals: IDocumentTotals): void {
+    items.forEach((item, index) => {
+      const category = totals.lineVatCategories[index];
+      // A decoded line keeps the category its document states (BT-151). One that is not S is a
+      // category the envelope cannot express (Z, E, K, G, O, or AE in a document that mixes S and
+      // AE lines, which the decoders do not read as reverse charge); its rate says nothing of BR-S-05.
+      const statedCategory = invoice.statedValues?.lines[index]?.vatCategoryCode;
+      if (category === 'S' && !(item.vatPercentage > 0) && (statedCategory === undefined || statedCategory === 'S')) {
+        this.addError('BR-S-05', {
+          field: `items[${index}].vatPercentage`,
+          btReference: 'BT-152',
+          bgReference: 'BG-25',
+          value: item.vatPercentage,
+          expected: '> 0',
+        });
+      }
+      if (category === 'AE' && item.vatPercentage !== 0) {
+        this.addError('BR-AE-05', {
+          field: `items[${index}].vatPercentage`,
+          btReference: 'BT-152',
+          bgReference: 'BG-25',
+          value: item.vatPercentage,
+          expected: 0,
+        });
+      }
+    });
+
+    const hasCategory = (category: TVatCategoryCode) => totals.lineVatCategories.includes(category);
+    const groupsOf = (category: TVatCategoryCode) => totals.vatGroups.filter((group) => group.category === category);
+    if (hasCategory('S') && groupsOf('S').length === 0) {
+      this.addError('BR-S-01', { field: 'taxBreakdown', btReference: 'BT-118' });
+    }
+    if (hasCategory('AE') && groupsOf('AE').length !== 1) {
+      this.addError('BR-AE-01', {
+        field: 'taxBreakdown',
+        btReference: 'BT-118',
+        value: groupsOf('AE').length,
+        expected: 1,
+        remediation: 'a reverse charge breakdown per rate: give every reverse charge line the VAT rate 0 (BR-AE-05)',
+      });
     }
-    
-    // BR-O-06: Must have exemption reason
-    if (!breakdown.exemptionReason && !breakdown.exemptionReasonCode) {
-      this.addError('BR-O-06',
-        'Out of scope services must have an exemption reason',
-        'taxBreakdown.exemptionReason'
-      );
+
+    if (hasCategory('AE')) {
+      const seller = invoice.from?.registrationDetails;
+      if (!seller?.vatId?.trim() && !seller?.taxNumber?.trim()) {
+        this.addError('BR-AE-02', {
+          field: 'from.registrationDetails',
+          btReference: 'BT-31',
+          bgReference: 'BG-4',
+          remediation: 'state from.registrationDetails.vatId (BT-31) or .taxNumber (BT-32); the envelope cannot state a tax representative (BT-63)',
+        });
+      }
+      const buyer = invoice.to?.registrationDetails;
+      if (!buyer?.vatId?.trim() && !buyer?.registrationId?.trim()) {
+        this.addError('BR-AE-02', {
+          field: 'to.registrationDetails',
+          bgReference: 'BG-7',
+          btReference: 'BT-48',
+          remediation: 'state to.registrationDetails.vatId (BT-48) or .registrationId (BT-47)',
+        });
+      }
     }
   }
-  
+
   /**
-   * Cross-category validation rules
+   * The rules on each VAT breakdown group: its taxable amount (BR-S-08, BR-AE-08), its tax
+   * amount (BR-S-09, BR-AE-09, BR-CO-17) and its exemption reason (BR-S-10, BR-AE-10)
    */
-  private validateCrossCategoryRules(
-    invoice: EInvoice,
-    itemsByCategory: Map<string, TAccountingDocItem[]>,
-    breakdownsByCategory: Map<string, any>
-  ): void {
-    // BR-CO-17: VAT category tax amount = Σ(VAT category taxable amount × VAT rate)
-    breakdownsByCategory.forEach((breakdown, category) => {
-      if (category === 'S' && breakdown.taxPercent > 0) {
-        const expectedTax = this.calculateVATAmount(breakdown.netAmount, breakdown.taxPercent);
-        if (!this.areAmountsEqual(breakdown.taxAmount, expectedTax)) {
-          this.addError('BR-CO-17',
-            `VAT tax amount calculation error for category ${category}`,
-            'taxBreakdown.taxAmount',
-            breakdown.taxAmount,
-            expectedTax
-          );
+  private validateBreakdown(items: TAccountingDocItem[], totals: IDocumentTotals, calculator: DecimalCurrencyCalculator): void {
+    for (const group of totals.vatGroups) {
+      const lineNetAmounts = totals.lineNetAmounts.filter(
+        (_, index) => totals.lineVatCategories[index] === group.category && items[index].vatPercentage === group.rate,
+      );
+      const expectedTaxable = calculator.round(Decimal.sum(lineNetAmounts));
+      const expectedTax = calculator.calculateVAT(group.taxableAmount, group.rate);
+      const amounts = (value: Decimal, expected: Decimal) => ({ value: value.toNumber(), expected: expected.toNumber() });
+      const at = `rate ${group.rate}`;
+
+      if (group.category === 'S') {
+        if (!group.taxableAmount.equals(expectedTaxable)) {
+          this.addError('BR-S-08', { field: `taxBreakdown[${at}].netAmount`, btReference: 'BT-116', ...amounts(group.taxableAmount, expectedTaxable) });
+        }
+        if (!group.taxAmount.equals(expectedTax)) {
+          this.addError('BR-S-09', { field: `taxBreakdown[${at}].taxAmount`, btReference: 'BT-117', ...amounts(group.taxAmount, expectedTax) });
+        }
+        if (group.exemption) {
+          this.addError('BR-S-10', { field: `taxBreakdown[${at}]`, btReference: 'BT-121', value: group.exemption.code });
         }
       }
-    });
-    
-    // BR-CO-18: Invoice with mixed VAT categories
-    const categoriesUsed = new Set<string>();
-    itemsByCategory.forEach((items, category) => {
-      if (items.length > 0) categoriesUsed.add(category);
-    });
-    
-    // BR-IC-01: Supply to EU countries without VAT ID should use standard rate
-    if (categoriesUsed.has('K') && !invoice.metadata?.buyerTaxId) {
-      this.addError('BR-IC-01',
-        'Intra-community supply requires buyer VAT identifier',
-        'metadata.buyerTaxId'
-      );
-    }
-    
-    // BR-IC-02: Reverse charge requires specific conditions
-    if (categoriesUsed.has('AE')) {
-      // Check for service codes that qualify for reverse charge
-      const hasQualifyingServices = invoice.items?.some(item => 
-        this.isReverseChargeService(item)
-      );
-      
-      if (!hasQualifyingServices) {
-        this.addWarning('BR-IC-02',
-          'Reverse charge should only be used for qualifying services',
-          'items'
-        );
-      }
-    }
-    
-    // BR-CO-19: Sum of VAT breakdown taxable amounts must equal invoice tax exclusive total
-    let totalTaxable = 0;
-    breakdownsByCategory.forEach(breakdown => {
-      totalTaxable += breakdown.netAmount || 0;
-    });
-    
-    const declaredTotal = invoice.totalNet || 0;
-    if (!this.areAmountsEqual(totalTaxable, declaredTotal)) {
-      this.addError('BR-CO-19',
-        'Sum of VAT breakdown taxable amounts must equal invoice total without VAT',
-        'totalNet',
-        declaredTotal,
-        totalTaxable
-      );
-    }
-  }
-  
-  // Helper methods
-  
-  private groupItemsByVATCategory(items: TAccountingDocItem[]): Map<string, TAccountingDocItem[]> {
-    const groups = new Map<string, TAccountingDocItem[]>();
-    
-    items.forEach(item => {
-      const category = this.determineVATCategory(item);
-      if (!groups.has(category)) {
-        groups.set(category, []);
+      if (group.category === 'AE') {
+        if (!group.taxableAmount.equals(expectedTaxable)) {
+          this.addError('BR-AE-08', { field: `taxBreakdown[${at}].netAmount`, btReference: 'BT-116', ...amounts(group.taxableAmount, expectedTaxable) });
+        }
+        if (!group.taxAmount.isZero()) {
+          this.addError('BR-AE-09', { field: `taxBreakdown[${at}].taxAmount`, btReference: 'BT-117', value: group.taxAmount.toNumber(), expected: 0 });
+        }
+        if (group.exemption?.code !== 'VATEX-EU-AE' && !group.exemption?.reason.trim()) {
+          this.addError('BR-AE-10', { field: `taxBreakdown[${at}]`, btReference: 'BT-121' });
+        }
       }
-      groups.get(category)!.push(item);
-    });
-    
-    return groups;
-  }
-  
-  private groupBreakdownsByCategory(breakdowns: any[]): Map<string, any> {
-    const groups = new Map<string, any>();
-    
-    breakdowns.forEach(breakdown => {
-      const category = breakdown.categoryCode || this.inferCategoryFromRate(breakdown.taxPercent);
-      groups.set(category, breakdown);
-    });
-    
-    return groups;
-  }
-  
-  private determineVATCategory(item: TAccountingDocItem): string {
-    // Determine VAT category from item metadata or rate
-    const metadata = (item as any).metadata;
-    if (metadata?.vatCategory) {
-      return metadata.vatCategory;
-    }
-    
-    // Infer from rate
-    if (item.vatPercentage === undefined || item.vatPercentage === null) {
-      return 'S'; // Default to standard
-    } else if (item.vatPercentage > 0) {
-      return 'S'; // Standard rate
-    } else if (item.vatPercentage === 0) {
-      // Could be Z, E, AE, K, G, or O - need more context
-      if (metadata?.exemptionReason) {
-        if (metadata.exemptionReason.includes('reverse')) return 'AE';
-        if (metadata.exemptionReason.includes('intra')) return 'K';
-        if (metadata.exemptionReason.includes('export')) return 'G';
-        if (metadata.exemptionReason.includes('scope')) return 'O';
-        return 'E'; // Default exempt
+      if (!group.taxAmount.equals(expectedTax)) {
+        this.addError('BR-CO-17', { field: `taxBreakdown[${at}].taxAmount`, btReference: 'BT-117', ...amounts(group.taxAmount, expectedTax) });
       }
-      return 'Z'; // Default zero-rated
     }
-    
-    return 'S'; // Default
-  }
-  
-  private inferCategoryFromRate(rate?: number): string {
-    if (!rate || rate === 0) return 'Z';
-    if (rate > 0) return 'S';
-    return 'S';
-  }
-  
-  private calculateTaxableAmount(items: TAccountingDocItem[]): number {
-    const total = items.reduce((sum, item) => {
-      const lineNet = (item.unitNetPrice || 0) * (item.unitQuantity || 0);
-      return sum + (this.currencyCalculator ? this.currencyCalculator.round(lineNet) : lineNet);
-    }, 0);
-    
-    return this.currencyCalculator ? this.currencyCalculator.round(total) : total;
   }
-  
-  private calculateVATAmount(taxableAmount: number, rate: number): number {
-    const vat = taxableAmount * (rate / 100);
-    return this.currencyCalculator ? this.currencyCalculator.round(vat) : vat;
-  }
-  
-  private areAmountsEqual(value1: number, value2: number): boolean {
-    if (this.currencyCalculator) {
-      return this.currencyCalculator.areEqual(value1, value2);
-    }
-    return Math.abs(value1 - value2) < 0.01;
-  }
-  
-  private isEUCountry(countryCode: string): boolean {
-    return isEuMemberState(countryCode);
-  }
-  
-  private isReverseChargeService(item: TAccountingDocItem): boolean {
-    // Check if item qualifies for reverse charge
-    // This would typically check service codes
-    const metadata = (item as any).metadata;
-    if (metadata?.serviceCode) {
-      // Construction services, telecommunication, etc.
-      const reverseChargeServices = ['44', '45', '61', '62'];
-      return reverseChargeServices.some(code => 
-        metadata.serviceCode.startsWith(code)
-      );
-    }
-    return false;
-  }
-  
-  private addError(
-    ruleId: string,
-    message: string,
-    field?: string,
-    value?: any,
-    expected?: any
-  ): void {
+
+  private addError(ruleId: TVatCategoryRuleId, finding: IVatCategoryFinding): void {
     this.results.push({
       ruleId,
       source: 'EN16931',
       severity: 'error',
-      message,
-      field,
-      value,
-      expected,
-      btReference: this.getBTReference(ruleId),
-      bgReference: 'BG-23' // VAT breakdown
+      message: VAT_CATEGORY_RULES[ruleId],
+      bgReference: 'BG-23',
+      ...finding,
     });
   }
-  
-  private addWarning(
-    ruleId: string,
-    message: string,
-    field?: string,
-    value?: any,
-    expected?: any
-  ): void {
-    this.results.push({
-      ruleId,
-      source: 'EN16931',
-      severity: 'warning',
-      message,
-      field,
-      value,
-      expected,
-      btReference: this.getBTReference(ruleId),
-      bgReference: 'BG-23'
-    });
-  }
-  
-  private getBTReference(ruleId: string): string | undefined {
-    const btMap: Record<string, string> = {
-      'BR-S-': 'BT-118', // VAT category rate
-      'BR-Z-': 'BT-118',
-      'BR-E-': 'BT-120', // VAT exemption reason
-      'BR-AE-': 'BT-120',
-      'BR-K-': 'BT-120',
-      'BR-G-': 'BT-120',
-      'BR-O-': 'BT-120',
-      'BR-CO-17': 'BT-117', // VAT category tax amount
-      'BR-CO-18': 'BT-118',
-      'BR-CO-19': 'BT-116'  // VAT category taxable amount
-    };
-    
-    for (const [prefix, bt] of Object.entries(btMap)) {
-      if (ruleId.startsWith(prefix)) {
-        return bt;
-      }
-    }
-    
-    return undefined;
-  }
 }
 
 /**