cosmemilton-acbr-node 0.1.2 → 0.2.0

package/docs/DEPENDENCIAS-NATIVAS.md

@@ -1,93 +1,93 @@
-# Reconstrução gratuita das DLLs Windows x64
-
-O motor Pascal usa OpenSSL 3 e libxml2 como bibliotecas dinâmicas. As DLLs distribuídas podem ser reconstruídas no Ubuntu 24.04/WSL com MinGW-w64, sem compilador comercial e sem Visual C++ Redistributable.
-
-A receita fixa OpenSSL **3.5.9** e libxml2 **2.15.4**. Usa os arquivos oficiais e confere SHA-256 antes de extrair ou compilar:
-
-| Fonte | SHA-256 |
-| --- | --- |
-| `openssl-3.5.9.tar.gz` | `603f5602e2eef00d77fbd429d34dcd5822bb301757a1bc9cdb24c670f1eb859a` |
-| `libxml2-2.15.4.tar.xz` | `98087fd181d9070724f3fbc65c7377db03038eb92bd882374daff44940138821` |
-
-Os hashes foram comparados aos arquivos publicados pelos projetos: [OpenSSL 3.5.9 e checksum](https://github.com/openssl/openssl/releases/tag/openssl-3.5.9), [checksum libxml2](https://download.gnome.org/sources/libxml2/2.15/libxml2-2.15.4.sha256sum). O script contém as URLs exatas dos tarballs e dos respectivos checksums.
-
-## Ferramentas e execução
-
-No Ubuntu 24.04/WSL:
-
-```sh
-sudo apt-get update
-sudo apt-get install gcc-mingw-w64-x86-64 g++-mingw-w64-x86-64 \
-  binutils-mingw-w64-x86-64 cmake ninja-build make perl curl tar xz-utils
-```
-
-Na raiz deste projeto:
-
-```sh
-node scripts/build-native-deps.mjs --project "$PWD"
-```
-
-O script do pacote instalado também pode ser usado:
-
-```sh
-node node_modules/cosmemilton-acbr-node/scripts/build-native-deps.mjs \
-  --project "$PWD"
-```
-
-Downloads ficam em `.acbr/deps/downloads`; fontes, objetos, instalação intermediária e logs ficam em `.acbr/deps/build/windows`. Os arquivos finais ficam em `.acbr/deps/win32-x64`. O comando não compila o motor ACBr e não acessa serviços fiscais.
-
-Para aproveitar tarballs já disponíveis, indique os arquivos. O hash continua obrigatório; os arquivos originais são somente lidos:
-
-```sh
-node scripts/build-native-deps.mjs --project "$PWD" --jobs 4 \
-  --openssl-archive /caminho/openssl-3.5.9.tar.gz \
-  --libxml2-archive /caminho/libxml2-2.15.4.tar.xz
-```
-
-Após uma interrupção, `--resume` reaproveita a configuração OpenSSL existente somente se revisão, argumentos e ambiente coincidirem. Use a mesma instalação de ferramentas; após mudar o compilador, execute o comando sem essa opção para reconfigurar. A reutilização aparece em `SOURCE.json`.
-
-Cada comando tem seu log em `.acbr/deps/build/windows/logs`. Em falhas, o script informa o caminho e o final do log. Apenas depois de todas as compilações e auditorias bem-sucedidas substitui as DLLs finais e remove os artefatos temporários conhecidos do build anterior com MSVC.
-
-## Configuração do build
-
-O OpenSSL é configurado como `mingw64 shared`, com assembly x64, `-static-libgcc`, timestamp PE fixo e provider `legacy`. A compilação cruzada segue o [procedimento oficial MinGW](https://github.com/openssl/openssl/blob/openssl-3.5.9/NOTES-WINDOWS.md) e a [documentação de instalação](https://github.com/openssl/openssl/blob/openssl-3.5.9/INSTALL.md).
-
-O libxml2 usa CMake/Ninja, compilador `x86_64-w64-mingw32-gcc-win32` e biblioteca compartilhada. XML Schema, C14N, threads, XPath e serialização permanecem habilitados. Python, iconv, ICU, zlib, HTTP e APIs legacy opcionais ficam desabilitados; os documentos NF-e usam UTF-8. As opções são as do `CMakeLists.txt` incluído no [tarball oficial libxml2 2.15.4](https://download.gnome.org/sources/libxml2/2.15/libxml2-2.15.4.tar.xz).
-
-O GCC usa o modelo de threads Win32 e o runtime GCC estático. O libxml2 também recebe `-static-libstdc++` no link, embora seu código seja C. Não se distribuem `libgcc_s`, `libstdc++`, `libwinpthread` nem `vcruntime140`; `msvcrt.dll` é um componente do próprio Windows. A auditoria dos imports PE rejeita qualquer dependência fora das quatro DLLs produzidas e da lista explícita de DLLs do sistema.
-
-`SOURCE_DATE_EPOCH=0` e `--no-insert-timestamp` reduzem variação de timestamps. O manifesto registra ferramentas, argumentos e hashes reais dos binários; não afirma identidade binária entre versões diferentes de compilador ou diretórios de build.
-
-## Artefatos, licenças e staging
-
-A saída inclui:
-
-- `libcrypto-3-x64.dll`, `libssl-3-x64.dll`, `legacy.dll` e `libxml2.dll`;
-- licença original adjacente `<DLL>.LICENSE` para cada DLL;
-- `GCC-Runtime.LICENSE`, `GCC-GPL-3.LICENSE` e `MinGW-w64.LICENSE`, que preservam os avisos do código de runtime incorporado;
-- `SOURCE.json` com URLs, versões, hashes dos fontes/binários, comandos, ferramentas e imports PE.
-
-OpenSSL preserva Apache-2.0; libxml2 preserva sua licença MIT. O arquivo do GCC contém a [GCC Runtime Library Exception 3.1](https://www.gnu.org/licenses/gcc-exception-3.1.html), além dos avisos aplicáveis. Os avisos MinGW-w64 vêm do pacote instalado, sem substituir os textos originais por uma licença genérica do projeto.
-
-Para compilar o motor Windows, configure os caminhos das DLLs no arquivo de configuração usado pelo CLI, por exemplo:
-
-```json
-{
-  "native": {
-    "libraryFiles": [
-      ".acbr/deps/win32-x64/libcrypto-3-x64.dll",
-      ".acbr/deps/win32-x64/libssl-3-x64.dll",
-      ".acbr/deps/win32-x64/libxml2.dll"
-    ],
-    "providerFiles": [".acbr/deps/win32-x64/legacy.dll"]
-  }
-}
-```
-
-Mantenha os outros campos existentes de `acbr.config.json`, como compilador, projeto Pascal e diretório Lazarus. O build do motor faz o staging das DLLs, de todas as licenças e de `SOURCE.json`. O provider vai para `ossl-modules`; o processo auxiliar recebe `OPENSSL_MODULES` e `OPENSSL_CONF` do runtime gerado, sem depender dos diretórios da máquina que compilou o OpenSSL.
-
-## Validação
-
-A receita confere arquitetura PE x64, imports de todas as DLLs e exports essenciais de libxml2 para parsing, C14N e XML Schema. A compilação cruzada não executa a suíte upstream no Linux: os testes gerados são executáveis Windows. `SOURCE.json` registra explicitamente essa limitação.
-
-Depois do staging, execute os testes offline do worker no Windows: geração de XML, assinatura com certificado temporário, validação dos schemas e TLS contra servidor local. Essa etapa comprova o funcionamento das DLLs no alvo. Os testes locais não autorizam emissão ou transmissão fiscal.
+# Reconstrução gratuita das DLLs Windows x64
+
+O motor Pascal usa OpenSSL 3 e libxml2 como bibliotecas dinâmicas. As DLLs distribuídas podem ser reconstruídas no Ubuntu 24.04/WSL com MinGW-w64, sem compilador comercial e sem Visual C++ Redistributable.
+
+A receita fixa OpenSSL **3.5.9** e libxml2 **2.15.4**. Usa os arquivos oficiais e confere SHA-256 antes de extrair ou compilar:
+
+| Fonte | SHA-256 |
+| --- | --- |
+| `openssl-3.5.9.tar.gz` | `603f5602e2eef00d77fbd429d34dcd5822bb301757a1bc9cdb24c670f1eb859a` |
+| `libxml2-2.15.4.tar.xz` | `98087fd181d9070724f3fbc65c7377db03038eb92bd882374daff44940138821` |
+
+Os hashes foram comparados aos arquivos publicados pelos projetos: [OpenSSL 3.5.9 e checksum](https://github.com/openssl/openssl/releases/tag/openssl-3.5.9), [checksum libxml2](https://download.gnome.org/sources/libxml2/2.15/libxml2-2.15.4.sha256sum). O script contém as URLs exatas dos tarballs e dos respectivos checksums.
+
+## Ferramentas e execução
+
+No Ubuntu 24.04/WSL:
+
+```sh
+sudo apt-get update
+sudo apt-get install gcc-mingw-w64-x86-64 g++-mingw-w64-x86-64 \
+  binutils-mingw-w64-x86-64 cmake ninja-build make perl curl tar xz-utils
+```
+
+Na raiz deste projeto:
+
+```sh
+node scripts/build-native-deps.mjs --project "$PWD"
+```
+
+O script do pacote instalado também pode ser usado:
+
+```sh
+node node_modules/cosmemilton-acbr-node/scripts/build-native-deps.mjs \
+  --project "$PWD"
+```
+
+Downloads ficam em `.acbr/deps/downloads`; fontes, objetos, instalação intermediária e logs ficam em `.acbr/deps/build/windows`. Os arquivos finais ficam em `.acbr/deps/win32-x64`. O comando não compila o motor ACBr e não acessa serviços fiscais.
+
+Para aproveitar tarballs já disponíveis, indique os arquivos. O hash continua obrigatório; os arquivos originais são somente lidos:
+
+```sh
+node scripts/build-native-deps.mjs --project "$PWD" --jobs 4 \
+  --openssl-archive /caminho/openssl-3.5.9.tar.gz \
+  --libxml2-archive /caminho/libxml2-2.15.4.tar.xz
+```
+
+Após uma interrupção, `--resume` reaproveita a configuração OpenSSL existente somente se revisão, argumentos e ambiente coincidirem. Use a mesma instalação de ferramentas; após mudar o compilador, execute o comando sem essa opção para reconfigurar. A reutilização aparece em `SOURCE.json`.
+
+Cada comando tem seu log em `.acbr/deps/build/windows/logs`. Em falhas, o script informa o caminho e o final do log. Apenas depois de todas as compilações e auditorias bem-sucedidas substitui as DLLs finais e remove os artefatos temporários conhecidos do build anterior com MSVC.
+
+## Configuração do build
+
+O OpenSSL é configurado como `mingw64 shared`, com assembly x64, `-static-libgcc`, timestamp PE fixo e provider `legacy`. A compilação cruzada segue o [procedimento oficial MinGW](https://github.com/openssl/openssl/blob/openssl-3.5.9/NOTES-WINDOWS.md) e a [documentação de instalação](https://github.com/openssl/openssl/blob/openssl-3.5.9/INSTALL.md).
+
+O libxml2 usa CMake/Ninja, compilador `x86_64-w64-mingw32-gcc-win32` e biblioteca compartilhada. XML Schema, C14N, threads, XPath e serialização permanecem habilitados. Python, iconv, ICU, zlib, HTTP e APIs legacy opcionais ficam desabilitados; os documentos NF-e usam UTF-8. As opções são as do `CMakeLists.txt` incluído no [tarball oficial libxml2 2.15.4](https://download.gnome.org/sources/libxml2/2.15/libxml2-2.15.4.tar.xz).
+
+O GCC usa o modelo de threads Win32 e o runtime GCC estático. O libxml2 também recebe `-static-libstdc++` no link, embora seu código seja C. Não se distribuem `libgcc_s`, `libstdc++`, `libwinpthread` nem `vcruntime140`; `msvcrt.dll` é um componente do próprio Windows. A auditoria dos imports PE rejeita qualquer dependência fora das quatro DLLs produzidas e da lista explícita de DLLs do sistema.
+
+`SOURCE_DATE_EPOCH=0` e `--no-insert-timestamp` reduzem variação de timestamps. O manifesto registra ferramentas, argumentos e hashes reais dos binários; não afirma identidade binária entre versões diferentes de compilador ou diretórios de build.
+
+## Artefatos, licenças e staging
+
+A saída inclui:
+
+- `libcrypto-3-x64.dll`, `libssl-3-x64.dll`, `legacy.dll` e `libxml2.dll`;
+- licença original adjacente `<DLL>.LICENSE` para cada DLL;
+- `GCC-Runtime.LICENSE`, `GCC-GPL-3.LICENSE` e `MinGW-w64.LICENSE`, que preservam os avisos do código de runtime incorporado;
+- `SOURCE.json` com URLs, versões, hashes dos fontes/binários, comandos, ferramentas e imports PE.
+
+OpenSSL preserva Apache-2.0; libxml2 preserva sua licença MIT. O arquivo do GCC contém a [GCC Runtime Library Exception 3.1](https://www.gnu.org/licenses/gcc-exception-3.1.html), além dos avisos aplicáveis. Os avisos MinGW-w64 vêm do pacote instalado, sem substituir os textos originais por uma licença genérica do projeto.
+
+Para compilar o motor Windows, configure os caminhos das DLLs no arquivo de configuração usado pelo CLI, por exemplo:
+
+```json
+{
+  "native": {
+    "libraryFiles": [
+      ".acbr/deps/win32-x64/libcrypto-3-x64.dll",
+      ".acbr/deps/win32-x64/libssl-3-x64.dll",
+      ".acbr/deps/win32-x64/libxml2.dll"
+    ],
+    "providerFiles": [".acbr/deps/win32-x64/legacy.dll"]
+  }
+}
+```
+
+Mantenha os outros campos existentes de `acbr.config.json`, como compilador, projeto Pascal e diretório Lazarus. O build do motor faz o staging das DLLs, de todas as licenças e de `SOURCE.json`. O provider vai para `ossl-modules`; o processo auxiliar recebe `OPENSSL_MODULES` e `OPENSSL_CONF` do runtime gerado, sem depender dos diretórios da máquina que compilou o OpenSSL.
+
+## Validação
+
+A receita confere arquitetura PE x64, imports de todas as DLLs e exports essenciais de libxml2 para parsing, C14N e XML Schema. A compilação cruzada não executa a suíte upstream no Linux: os testes gerados são executáveis Windows. `SOURCE.json` registra explicitamente essa limitação.
+
+Depois do staging, execute os testes offline do worker no Windows: geração de XML, assinatura com certificado temporário, validação dos schemas e TLS contra servidor local. Essa etapa comprova o funcionamento das DLLs no alvo. Os testes locais não autorizam emissão ou transmissão fiscal.

package/docs/VALIDACAO.md

@@ -1,67 +1,67 @@
-# Validação da implementação
-
-Validações registradas em 08/10/2026 para a versão **0.1.0**. A publicação npm e sua automação pela branch `release` foram autorizadas pelo usuário em **09/10/2026**. Os artefatos estão preparados; a publicação ainda não foi executada neste registro.
-
-Em 09/10/2026, os nomes npm foram definidos sem escopo, seguindo os pacotes existentes `cosmemilton-ui` e `cosmemilton-report`: `cosmemilton-acbr-node`, `cosmemilton-acbr-node-linux-x64` e `cosmemilton-acbr-node-win32-x64`. Duas gerações consecutivas produziram os mesmos arquivos; somente o import do cliente gerado mudou. O contrato, os 204 modelos, o mapper Pascal, o lock e todos os arquivos dos runtimes Linux/Windows permanecem idênticos. Os manifests dos runtimes atualizam somente `generatedFileHashes` para vincular o import novo. Typecheck, bundles JavaScript e 27 testes focados do gerador, supervisor e auditoria passaram com os nomes finais. Nenhum motor foi recompilado.
-
-As validações anteriores de instalação ESM/CommonJS descritas abaixo usaram o namespace `@cosmemilton`. A aceitação dos nomes finais foi concluída em 09/10/2026 com os tarballs auditados, instalados fora do repositório: Linux com Node 22.12.0/24.15.0 e Windows nativo com Node 22.12.0/24.18.0, em ESM e CommonJS. Cada execução processou quatro documentos sintéticos (dois emitentes × modelos 55/65), com geração, assinatura e validação: 96 operações reais ao todo. O runtime foi resolvido pelo pacote instalado, sem compilador no PATH. Relatórios e hashes constam em `release/0.1.0/VALIDATION.json`; evidências locais em `.acbr/unscoped-consumer-evidence/`.
-
-A verificação completa com os nomes finais aprovou o typecheck e 38 testes, com quatro suítes nativas opt-in ignoradas; os motores mantêm a evidência anterior de 52 testes Linux e 52 Windows e os mesmos hashes. Auditoria e dry run dos três tarballs aprovados. Os exemplos públicos da documentação também foram conferidos: JavaScript gerou XML sintético usando o pacote instalado e TypeScript passou em modo estrito NodeNext. Nenhuma transmissão à SEFAZ foi realizada.
-
-O snapshot principal usa ACBr SVN **48590** e **204 tipos gerados**. O contrato é:
-
-```text
-e5a497cefe8e0e350a30da5cc04e88b35c38a98535893d52f878890260d1346d
-```
-
-Revisão e inventário dos fontes constam em `acbr.lock.json`. O manifesto `.acbr/generated/manifest.json` vincula fonte, contrato e SHA-256 dos modelos TypeScript, fábrica do cliente e mapper Pascal. O build verifica esses três arquivos antes e depois da compilação. Cada runtime inventaria e verifica os seus arquivos; revisão ou contrato divergentes são recusados.
-
-## Resultado das verificações
-
-| Verificação | Estado e evidência |
-| --- | --- |
-| Gerador FCL-passrc | **6 testes aprovados**: AST real, 204 tipos e RTC, herança/aliases, precedência das unidades, enums simbólicos, coleções `New/Items`, tipos desconhecidos, mudanças de contrato, determinismo e equivalência dos modelos extraídos com condicionais Linux/Windows. |
-| Geração nativa Windows | CLI `generate` executado no Windows com Free Pascal 3.2.2/FCL-passrc: extrator `extract-model.exe` PE, 204 tipos, r48590 e contrato idêntico ao Linux. Os SHA-256 dos três arquivos gerados também coincidiram entre as plataformas. |
-| Tipos e bundle Node | Typecheck e build final aprovados, bundles ESM/CommonJS e cliente gerado com resolução NodeNext conferidos. Entradas usam enums ACBr, strings decimais e datas civis; assinatura/protocolo/suplemento gerados pelo motor não são campos de entrada. |
-| Supervisor Node | **8 testes aprovados**: UTF-8, isolamento de emitentes, integridade/contrato, fila, cancelamento, crash, timeout, recuperação de resultado incerto e ausência de retry/segredos em erros aprovados. |
-| CLI/configuração/fontes | **11 testes aprovados** no registro `.acbr/cli-tests.log`: opções/revisões, init e colisões, caminhos relativos, origem SVN, snapshots, fontes alterados e concorrência. |
-| CLI check offline Linux/Windows | Quatro operações reais aprovadas em cada sistema após integridade: gerar XML55 sintético (mapper/chave/UTF-8), validar XML assinado com certificado público sintético, recusar XML malformado e recusar DTD/entidade externa. Sem credenciais A1 na configuração do smoke, sem acesso à rede ou transmissão. |
-| Motor Linux | **52 testes aprovados**: 27 do motor/TLS e 25 dos serviços SOAP locais. Incluem NF-e/NFC-e sintéticas, assinatura e schema, dados Unicode, datas/decimais/coleções, CSC/QRCode e casos de erro. |
-| Consumidor Linux com runtime instalado | **ESM e CommonJS aprovados com Node 24.15.0 e 22.12.0**. Para cada formato/versão: quatro documentos, dois emitentes sintéticos, modelos 55 e 65, 12 processos nas operações `gerarXml → assinar → validar`. Não foram chamados compiladores. |
-| Consumidor com revisão própria | Fluxo externo completo em **r48589**: init, atualização SVN, generate, build, check, doctor, TypeScript NodeNext e XML gerado pela fábrica própria. Contrato `369de708cd42003fc02a98397346d55b842ad3cb25a8422939bd7de0a00aad91`, distinto do snapshot principal. |
-| Dependências Windows | OpenSSL 3.5.9 e libxml2 2.15.4 recompilados de fontes oficiais com MinGW x64. SHA-256 dos fontes e imports/exports PE conferidos. DLLs não dependem de VC Redistributable nem de runtime GCC dinâmico externo. Licenças e `SOURCE.json` preservados. |
-| Motor Windows | Compilação e **rodada final de 52 testes aprovadas**: 20 do motor XML/A1/protocolo, sete TLS e 25 SOAP. Inclui NFC-e autorizada simulada (cStat 100), assinatura/QRCode/UTF-8 correlacionados e encerramento ao morrer o supervisor. |
-| Consumidor Windows com Node mínimo | **ESM e CommonJS aprovados com Node 22.12.0** em diretório externo. Cada formato executou quatro documentos (dois CNPJs × modelos 55/65) e 12 operações offline. O processo consumidor tinha apenas Node no `PATH`; o worker e as DLLs vieram do runtime instalado, sem execução de compiladores ou fontes do checkout. |
-| Distribuição e licenças | **7 testes de auditoria aprovados**, staging real Linux/Windows conferido e pack/dry-run dos três pacotes aprovados. Fontes, licenças e runtime inventariados. Tarballs de revisão em `.acbr/release-artifacts`: SDK cerca de 484 KiB, Linux 50 MiB e Windows 33 MiB. |
-| Docker / CI remota dos motores | **Não executados**. O Docker Desktop não tinha daemon disponível; os motores foram validados localmente em Linux/Windows. O workflow de publicação audita e publica esses tarballs, sem reconstruir os motores. |
-| Publicação npm | **Autorizada em 09/10/2026**, ainda não executada neste registro. A automação da branch `release` confere os tarballs contra hashes fixados em `release/0.1.0/manifest.json`. |
-
-A execução final de `npm test` teve **32 testes aprovados e quatro suítes opt-in ignoradas**: seis do gerador, 11 da CLI/configuração/fontes, oito do supervisor e sete de auditoria. Os testes nativos foram habilitados e executados separadamente: **52 Linux + 52 Windows**, sem falhas.
-
-As operações marcadas como XML, assinatura, schema e SOAP foram executadas contra o componente Pascal real e serviços locais sintéticos. Respostas simuladas não comprovam aceitação fiscal na SEFAZ.
-
-## Consumo sem compilação
-
-O teste `tests/package-install.mjs` instala somente os tarballs do SDK e do runtime em um diretório externo ao checkout, com npm offline e scripts de instalação desativados. O processo consumidor importa o pacote instalado em ESM/CommonJS; `criarEmissor` resolve o executável do pacote nativo sem `runtimeDirectory` ou caminho para o motor do repositório. Cada execução capturada corresponde ao worker instalado, com `PATH` restrito ao diretório do Node.
-
-No Linux, `LD_DEBUG=libs` confirmou OpenSSL, libxml2, ICU, zlib, liblzma, libgcc, libstdc++ e provider legacy dentro do runtime instalado. O sistema forneceu apenas glibc, loader, libm, libpthread e o módulo glibc `gconv/UTF-16.so`, confirmado como arquivo do pacote Ubuntu `libc6`. A evidência corresponde ao Ubuntu 24.04/glibc; não é um teste em container limpo nem uma validação de Alpine ou de qualquer distribuição Linux.
-
-Relatórios locais:
-
-- `.acbr/validation-evidence/consumers/acbr-node-runtime-consumer-linux-final/report-esm.json` e `report-cjs.json`: Node 24.15.0.
-- `.acbr/validation-evidence/consumers/acbr-node-runtime-consumer-linux-node22/report-esm.json` e `report-cjs.json`: Node 22.12.0.
-- `C:\SRI_SERVICES\acbr-node-runtime-consumer-win32-node22-final\report-esm.json` e `report-cjs.json`: Windows com Node 22.12.0.
-- `C:\SRI_SERVICES\acbr-node-generator-win32-final\generate.log`: geração FCL-passrc executada nativamente no Windows.
-- `.acbr/finish-consumer.log`: geração pela fábrica do consumidor r48589.
-- `.acbr/final-release-staging-audit.log`: inventário final de distribuição Linux/Windows.
-- `.acbr/cli-check-linux-offline.json` e `.acbr/cli-check-windows-offline.json`: hashes do runtime e quatro probes reais do CLI por plataforma.
-
-As cinco pastas temporárias de consumidores Linux foram removidas após preservar seus relatórios, scripts, locks, modelos gerados e logs em `.acbr/validation-evidence/consumers/`. O arquivo `archive-manifest.json` registra os caminhos originais e os hashes SHA-256 dos arquivos preservados. Os caminhos dentro dos relatórios correspondem ao local da execução original. As fixtures de certificados sintéticos podem ser recriadas por `tests/package-install.mjs`.
-
-Os binários portáteis Node 22.12.0 de teste foram obtidos de `nodejs.org/dist/v22.12.0` e conferidos contra `SHASUMS256.txt`, sem alterar o Node padrão da máquina.
-
-## Homologação fiscal separada
-
-Nenhum teste deste projeto transmite documentos à SEFAZ. Certificados, CNPJs, documentos e CAs usados nos testes são sintéticos. Homologação oficial com certificado habilitado, cenários fiscais reais por UF e verificação operacional permanecem pendentes e não fazem parte da evidência dos testes locais.
-
-A verificação de TLS não inclui consulta de revogação CRL/OCSP nesta versão. DANFE, impressão e A3 ficam fora do escopo atual.
+# Validação da implementação
+
+Validações registradas em 08/10/2026 para a versão **0.1.0**. A publicação npm e sua automação pela branch `release` foram autorizadas pelo usuário em **09/10/2026**. Os artefatos estão preparados; a publicação ainda não foi executada neste registro.
+
+Em 09/10/2026, os nomes npm foram definidos sem escopo, seguindo os pacotes existentes `cosmemilton-ui` e `cosmemilton-report`: `cosmemilton-acbr-node`, `cosmemilton-acbr-node-linux-x64` e `cosmemilton-acbr-node-win32-x64`. Duas gerações consecutivas produziram os mesmos arquivos; somente o import do cliente gerado mudou. O contrato, os 204 modelos, o mapper Pascal, o lock e todos os arquivos dos runtimes Linux/Windows permanecem idênticos. Os manifests dos runtimes atualizam somente `generatedFileHashes` para vincular o import novo. Typecheck, bundles JavaScript e 27 testes focados do gerador, supervisor e auditoria passaram com os nomes finais. Nenhum motor foi recompilado.
+
+As validações anteriores de instalação ESM/CommonJS descritas abaixo usaram o namespace `@cosmemilton`. A aceitação dos nomes finais foi concluída em 09/10/2026 com os tarballs auditados, instalados fora do repositório: Linux com Node 22.12.0/24.15.0 e Windows nativo com Node 22.12.0/24.18.0, em ESM e CommonJS. Cada execução processou quatro documentos sintéticos (dois emitentes × modelos 55/65), com geração, assinatura e validação: 96 operações reais ao todo. O runtime foi resolvido pelo pacote instalado, sem compilador no PATH. Relatórios e hashes constam em `release/0.1.0/VALIDATION.json`; evidências locais em `.acbr/unscoped-consumer-evidence/`.
+
+A verificação completa com os nomes finais aprovou o typecheck e 38 testes, com quatro suítes nativas opt-in ignoradas; os motores mantêm a evidência anterior de 52 testes Linux e 52 Windows e os mesmos hashes. Auditoria e dry run dos três tarballs aprovados. Os exemplos públicos da documentação também foram conferidos: JavaScript gerou XML sintético usando o pacote instalado e TypeScript passou em modo estrito NodeNext. Nenhuma transmissão à SEFAZ foi realizada.
+
+O snapshot principal usa ACBr SVN **48590** e **204 tipos gerados**. O contrato é:
+
+```text
+e5a497cefe8e0e350a30da5cc04e88b35c38a98535893d52f878890260d1346d
+```
+
+Revisão e inventário dos fontes constam em `acbr.lock.json`. O manifesto `.acbr/generated/manifest.json` vincula fonte, contrato e SHA-256 dos modelos TypeScript, fábrica do cliente e mapper Pascal. O build verifica esses três arquivos antes e depois da compilação. Cada runtime inventaria e verifica os seus arquivos; revisão ou contrato divergentes são recusados.
+
+## Resultado das verificações
+
+| Verificação | Estado e evidência |
+| --- | --- |
+| Gerador FCL-passrc | **6 testes aprovados**: AST real, 204 tipos e RTC, herança/aliases, precedência das unidades, enums simbólicos, coleções `New/Items`, tipos desconhecidos, mudanças de contrato, determinismo e equivalência dos modelos extraídos com condicionais Linux/Windows. |
+| Geração nativa Windows | CLI `generate` executado no Windows com Free Pascal 3.2.2/FCL-passrc: extrator `extract-model.exe` PE, 204 tipos, r48590 e contrato idêntico ao Linux. Os SHA-256 dos três arquivos gerados também coincidiram entre as plataformas. |
+| Tipos e bundle Node | Typecheck e build final aprovados, bundles ESM/CommonJS e cliente gerado com resolução NodeNext conferidos. Entradas usam enums ACBr, strings decimais e datas civis; assinatura/protocolo/suplemento gerados pelo motor não são campos de entrada. |
+| Supervisor Node | **8 testes aprovados**: UTF-8, isolamento de emitentes, integridade/contrato, fila, cancelamento, crash, timeout, recuperação de resultado incerto e ausência de retry/segredos em erros aprovados. |
+| CLI/configuração/fontes | **11 testes aprovados** no registro `.acbr/cli-tests.log`: opções/revisões, init e colisões, caminhos relativos, origem SVN, snapshots, fontes alterados e concorrência. |
+| CLI check offline Linux/Windows | Quatro operações reais aprovadas em cada sistema após integridade: gerar XML55 sintético (mapper/chave/UTF-8), validar XML assinado com certificado público sintético, recusar XML malformado e recusar DTD/entidade externa. Sem credenciais A1 na configuração do smoke, sem acesso à rede ou transmissão. |
+| Motor Linux | **52 testes aprovados**: 27 do motor/TLS e 25 dos serviços SOAP locais. Incluem NF-e/NFC-e sintéticas, assinatura e schema, dados Unicode, datas/decimais/coleções, CSC/QRCode e casos de erro. |
+| Consumidor Linux com runtime instalado | **ESM e CommonJS aprovados com Node 24.15.0 e 22.12.0**. Para cada formato/versão: quatro documentos, dois emitentes sintéticos, modelos 55 e 65, 12 processos nas operações `gerarXml → assinar → validar`. Não foram chamados compiladores. |
+| Consumidor com revisão própria | Fluxo externo completo em **r48589**: init, atualização SVN, generate, build, check, doctor, TypeScript NodeNext e XML gerado pela fábrica própria. Contrato `369de708cd42003fc02a98397346d55b842ad3cb25a8422939bd7de0a00aad91`, distinto do snapshot principal. |
+| Dependências Windows | OpenSSL 3.5.9 e libxml2 2.15.4 recompilados de fontes oficiais com MinGW x64. SHA-256 dos fontes e imports/exports PE conferidos. DLLs não dependem de VC Redistributable nem de runtime GCC dinâmico externo. Licenças e `SOURCE.json` preservados. |
+| Motor Windows | Compilação e **rodada final de 52 testes aprovadas**: 20 do motor XML/A1/protocolo, sete TLS e 25 SOAP. Inclui NFC-e autorizada simulada (cStat 100), assinatura/QRCode/UTF-8 correlacionados e encerramento ao morrer o supervisor. |
+| Consumidor Windows com Node mínimo | **ESM e CommonJS aprovados com Node 22.12.0** em diretório externo. Cada formato executou quatro documentos (dois CNPJs × modelos 55/65) e 12 operações offline. O processo consumidor tinha apenas Node no `PATH`; o worker e as DLLs vieram do runtime instalado, sem execução de compiladores ou fontes do checkout. |
+| Distribuição e licenças | **7 testes de auditoria aprovados**, staging real Linux/Windows conferido e pack/dry-run dos três pacotes aprovados. Fontes, licenças e runtime inventariados. Tarballs de revisão em `.acbr/release-artifacts`: SDK cerca de 484 KiB, Linux 50 MiB e Windows 33 MiB. |
+| Docker / CI remota dos motores | **Não executados**. O Docker Desktop não tinha daemon disponível; os motores foram validados localmente em Linux/Windows. O workflow de publicação audita e publica esses tarballs, sem reconstruir os motores. |
+| Publicação npm | **Autorizada em 09/10/2026**, ainda não executada neste registro. A automação da branch `release` confere os tarballs contra hashes fixados em `release/0.1.0/manifest.json`. |
+
+A execução final de `npm test` teve **32 testes aprovados e quatro suítes opt-in ignoradas**: seis do gerador, 11 da CLI/configuração/fontes, oito do supervisor e sete de auditoria. Os testes nativos foram habilitados e executados separadamente: **52 Linux + 52 Windows**, sem falhas.
+
+As operações marcadas como XML, assinatura, schema e SOAP foram executadas contra o componente Pascal real e serviços locais sintéticos. Respostas simuladas não comprovam aceitação fiscal na SEFAZ.
+
+## Consumo sem compilação
+
+O teste `tests/package-install.mjs` instala somente os tarballs do SDK e do runtime em um diretório externo ao checkout, com npm offline e scripts de instalação desativados. O processo consumidor importa o pacote instalado em ESM/CommonJS; `criarEmissor` resolve o executável do pacote nativo sem `runtimeDirectory` ou caminho para o motor do repositório. Cada execução capturada corresponde ao worker instalado, com `PATH` restrito ao diretório do Node.
+
+No Linux, `LD_DEBUG=libs` confirmou OpenSSL, libxml2, ICU, zlib, liblzma, libgcc, libstdc++ e provider legacy dentro do runtime instalado. O sistema forneceu apenas glibc, loader, libm, libpthread e o módulo glibc `gconv/UTF-16.so`, confirmado como arquivo do pacote Ubuntu `libc6`. A evidência corresponde ao Ubuntu 24.04/glibc; não é um teste em container limpo nem uma validação de Alpine ou de qualquer distribuição Linux.
+
+Relatórios locais:
+
+- `.acbr/validation-evidence/consumers/acbr-node-runtime-consumer-linux-final/report-esm.json` e `report-cjs.json`: Node 24.15.0.
+- `.acbr/validation-evidence/consumers/acbr-node-runtime-consumer-linux-node22/report-esm.json` e `report-cjs.json`: Node 22.12.0.
+- `C:\SRI_SERVICES\acbr-node-runtime-consumer-win32-node22-final\report-esm.json` e `report-cjs.json`: Windows com Node 22.12.0.
+- `C:\SRI_SERVICES\acbr-node-generator-win32-final\generate.log`: geração FCL-passrc executada nativamente no Windows.
+- `.acbr/finish-consumer.log`: geração pela fábrica do consumidor r48589.
+- `.acbr/final-release-staging-audit.log`: inventário final de distribuição Linux/Windows.
+- `.acbr/cli-check-linux-offline.json` e `.acbr/cli-check-windows-offline.json`: hashes do runtime e quatro probes reais do CLI por plataforma.
+
+As cinco pastas temporárias de consumidores Linux foram removidas após preservar seus relatórios, scripts, locks, modelos gerados e logs em `.acbr/validation-evidence/consumers/`. O arquivo `archive-manifest.json` registra os caminhos originais e os hashes SHA-256 dos arquivos preservados. Os caminhos dentro dos relatórios correspondem ao local da execução original. As fixtures de certificados sintéticos podem ser recriadas por `tests/package-install.mjs`.
+
+Os binários portáteis Node 22.12.0 de teste foram obtidos de `nodejs.org/dist/v22.12.0` e conferidos contra `SHASUMS256.txt`, sem alterar o Node padrão da máquina.
+
+## Homologação fiscal separada
+
+Nenhum teste deste projeto transmite documentos à SEFAZ. Certificados, CNPJs, documentos e CAs usados nos testes são sintéticos. Homologação oficial com certificado habilitado, cenários fiscais reais por UF e verificação operacional permanecem pendentes e não fazem parte da evidência dos testes locais.
+
+A verificação de TLS não inclui consulta de revogação CRL/OCSP nesta versão. DANFE, impressão e A3 ficam fora do escopo atual.

package/docs/examples/recuperar-xml.mjs

@@ -0,0 +1,54 @@
+// Exemplo da aplicação, sem execução automática ao importar.
+// Nos testes: XML/A1 sintéticos e serviço SOAP local, sem SEFAZ real.
+// O chamador fornece caminhos privados, configuração, A1 e confirmação.
+// Não receba senha/PFX por argv ou env e não registre esses valores.
+// Apresente falhas ao usuário com diagnosticarErro, sem imprimir o erro bruto.
+// opcoes é opcional e aceita somente signal?: AbortSignal, de um AbortController.
+// abort() solicita cancelamento no SDK; a consulta pode já ter sido enviada.
+// Isso não cancela a autorização fiscal.
+import { readFile } from 'node:fs/promises';
+import { criarEmissor, diagnosticarResultado } from 'cosmemilton-acbr-node';
+
+export async function recuperarXmlDeArquivo({
+  arquivoAssinado,
+  configuracao,
+  certificado,
+  confirmarConsulta,
+  opcoes
+}) {
+  if (configuracao?.ambiente !== 2 || typeof confirmarConsulta !== 'function') {
+    throw new TypeError('Este exemplo exige homologação e confirmação da aplicação.');
+  }
+  const original = await readFile(arquivoAssinado);
+  const xmlAssinado = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(original);
+  if (!Buffer.from(xmlAssinado, 'utf8').equals(original)) {
+    throw new TypeError('O arquivo assinado precisa estar em UTF-8.');
+  }
+  if (await confirmarConsulta('Consultar uma vez para recuperar o XML autorizado, sem emitir ou transmitir a nota?') !== true) {
+    return { recuperado: false, confirmado: false };
+  }
+
+  const emissor = criarEmissor({ ...configuracao, ambiente: 2, certificado });
+  try {
+    // Única operação fiscal deste exemplo. É uma consulta externa com A1.
+    const resultado = await emissor.recuperarXml(xmlAssinado, opcoes);
+    const diagnostico = resultado.diagnostico ?? diagnosticarResultado(resultado, 'recuperarXml');
+    if (!(await readFile(arquivoAssinado)).equals(original)) {
+      throw new Error('O arquivo original mudou durante a operação; preserve os registros.');
+    }
+    if (resultado.sucesso !== true || resultado.estado !== 'XML_RECUPERADO'
+        || resultado.cStat !== 100 || resultado.envioIniciado === true
+        || typeof resultado.xmlBase64 !== 'string' || !resultado.xmlBase64) {
+      return { recuperado: false, diagnostico };
+    }
+    const bytes = Buffer.from(resultado.xmlBase64, 'base64');
+    if (bytes.toString('base64') !== resultado.xmlBase64) {
+      throw new Error('O motor não devolveu o XML recuperado em base64 íntegro.');
+    }
+    // Dados fiscais privados: não imprima o objeto ou os bytes em logs.
+    // O chamador pode salvar em um NOVO arquivo com writeFile(..., { flag: 'wx' }).
+    return { recuperado: true, bytes, diagnostico };
+  } finally {
+    await emissor.fechar();
+  }
+}

package/docs/licenses/fpc/COPYING.FPC

@@ -1,25 +1,25 @@
-This is the file COPYING.FPC, it applies to the Free Pascal Run-Time Library 
-(RTL) and packages (packages) distributed by members of the Free Pascal 
-Development Team.
-
-The source code of the Free Pascal Runtime Libraries and packages are 
-distributed under the Library GNU General Public License 
-(see the file COPYING) with the following modification:
-
-As a special exception, the copyright holders of this library give you
-permission to link this library with independent modules to produce an
-executable, regardless of the license terms of these independent modules,
-and to copy and distribute the resulting executable under terms of your choice,
-provided that you also meet, for each linked independent module, the terms
-and conditions of the license of that module. An independent module is a module
-which is not derived from or based on this library. If you modify this
-library, you may extend this exception to your version of the library, but you are
-not obligated to do so. If you do not wish to do so, delete this exception
-statement from your version.
-
-If you didn't receive a copy of the file COPYING, contact:
-      Free Software Foundation
-      675 Mass Ave
-      Cambridge, MA  02139
-      USA
-
+This is the file COPYING.FPC, it applies to the Free Pascal Run-Time Library 
+(RTL) and packages (packages) distributed by members of the Free Pascal 
+Development Team.
+
+The source code of the Free Pascal Runtime Libraries and packages are 
+distributed under the Library GNU General Public License 
+(see the file COPYING) with the following modification:
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent modules,
+and to copy and distribute the resulting executable under terms of your choice,
+provided that you also meet, for each linked independent module, the terms
+and conditions of the license of that module. An independent module is a module
+which is not derived from or based on this library. If you modify this
+library, you may extend this exception to your version of the library, but you are
+not obligated to do so. If you do not wish to do so, delete this exception
+statement from your version.
+
+If you didn't receive a copy of the file COPYING, contact:
+      Free Software Foundation
+      675 Mass Ave
+      Cambridge, MA  02139
+      USA
+