cosmemilton-acbr-node 0.1.2 → 0.2.0

package/dist/types/src/types.d.ts

@@ -1,7 +1,7 @@
 export declare const PROTOCOL_VERSION: 1;
 export type Modelo = 55 | 65;
 export type Ambiente = 1 | 2;
-export type Comando = 'gerarXml' | 'validar' | 'assinar' | 'transmitir' | 'consultar' | 'cancelar' | 'cartaCorrecao' | 'inutilizar';
+export type Comando = 'gerarXml' | 'validar' | 'assinar' | 'transmitir' | 'consultar' | 'recuperarXml' | 'cancelar' | 'cartaCorrecao' | 'inutilizar';
 export interface Contrato {
     sourceRevision: number;
     contractHash: string;
@@ -48,7 +48,7 @@ export interface RequisicaoMotor extends Contrato {
         numeroFinal: number;
     };
 }
-export type Estado = 'DENEGADO' | 'XML_GERADO' | 'VALIDADO' | 'ASSINADO' | 'AUTORIZADO' | 'REJEITADO' | 'PENDENTE' | 'INDETERMINADO' | 'CONSULTADO' | 'CANCELADO' | 'EVENTO_REGISTRADO' | 'INUTILIZADO' | 'ERRO';
+export type Estado = 'DENEGADO' | 'XML_GERADO' | 'VALIDADO' | 'ASSINADO' | 'XML_RECUPERADO' | 'AUTORIZADO' | 'REJEITADO' | 'PENDENTE' | 'INDETERMINADO' | 'CONSULTADO' | 'CANCELADO' | 'EVENTO_REGISTRADO' | 'INUTILIZADO' | 'ERRO';
 export interface ResultadoFiscal extends Contrato {
     versao: 1;
     id: string;
@@ -71,6 +71,8 @@ export interface RuntimeManifest extends Contrato {
     arch: string;
     executable: string;
     files: Record<string, string>;
+    /** Operações adicionais anunciadas pelo motor, sem alterar o protocolo-base. */
+    capabilities?: readonly string[];
 }
 export interface OpcoesOperacao {
     signal?: AbortSignal;

package/docs/API.md

@@ -1,90 +1,116 @@
-# API e protocolo
-
-`criarEmissor` retorna operações assíncronas; cada chamada inicia um processo fiscal isolado. Uma instância processa uma operação por vez, com fila limitada. Emitentes diferentes não compartilham o componente Pascal.
-
-## Configuração
-
-Campos obrigatórios: `cnpj` (14 dígitos), `uf`, `modelo` (55/65), `ambiente` (1 produção, 2 homologação). Certificado A1: `certificado: { pfx: Uint8Array, senha: string }` ou `{ arquivo: string, senha: string }`. NFC-e requer `csc: { id: string, valor: string }` para os recursos que dependem do CSC.
-
-`timeoutMs` tem padrão/máximo de 120.000 ms; `limiteFila` tem padrão 32. `runtimeDirectory` seleciona um runtime próprio cujo contrato deve coincidir com o cliente. Cada operação aceita `{ signal: AbortSignal }` como último argumento. `fechar()` cancela a fila, encerra e aguarda o processo em execução.
-
-Com `limiteFila: 0`, uma operação pode executar e chamadas concorrentes recebem
-`FILA_CHEIA`. Após o `await` dessa operação, a fila já está disponível para a
-próxima chamada; isso também vale quando a operação termina com erro, salvo
-quando o emissor foi fechado ou o encerramento do motor não foi confirmado.
-
-## Operações
-
-| Método | Entrada |
-| --- | --- |
-| `gerarXml` | Objeto TNFe/TNFeInput com nomes ACBr |
-| `assinar`, `validar`, `transmitir` | XML UTF-8 como string |
-| `consultar` | `{ chave, recibo? }` |
-| `cancelar` | `{ chave, protocolo, justificativa }` |
-| `cartaCorrecao` | `{ chave, correcao, sequenciaEvento? }`; modelo 55 |
-| `inutilizar` | `{ ano, serie, numeroInicial, numeroFinal, justificativa }`; ano com 2 dígitos |
-
-A resposta `ResultadoFiscal` contém `sucesso`, `estado`, revisão/hash do contrato e, quando disponíveis, `cStat`, `xMotivo`, `chave`, `protocolo`, `recibo` e `xmlBase64`. `sucesso` deve ser conferido antes de usar o resultado. XML é devolvido em base64 para preservar os bytes UTF-8.
-
-Rejeições fiscais e recibos pendentes são resultados, sem retry automático. Falhas no supervisor lançam `ErroAcbrNode` com `codigo` e `resultadoDesconhecido`. Em falha/timeout de uma operação que pode ter iniciado envio, consulte a situação fiscal antes de decidir uma nova transmissão. O erro de transmissão conserva `xmlBase64` para recuperação.
-
-## Feedback seguro para o usuário
-
-Os resultados incluem `diagnostico`, com `codigo`, `etapa`, `mensagem`, `acao`,
-`statusEnvio` e, quando disponíveis, `campo` e `cStat`. Também estão disponíveis
-os helpers `diagnosticarErro(erro)` e `diagnosticarResultado(resultado, comando)`.
-Use esse resumo nas interfaces e nos logs. Ele não copia XML, identidade fiscal,
-caminhos, senha, `xMotivo`, stderr, stack ou causa bruta.
-
-```ts
-import { TNFe, diagnosticarErro, diagnosticarResultado } from 'cosmemilton-acbr-node';
-
-try {
-  const resultado = await emissor.gerarXml(new TNFe(dados));
-  const d = resultado.diagnostico ?? diagnosticarResultado(resultado, 'gerarXml');
-  mostrarAoUsuario(d); // Apresente mensagem, campo, ação e statusEnvio.
-} catch (erro) {
-  mostrarAoUsuario(diagnosticarErro(erro)); // Não registre o erro bruto.
-}
-```
-
-As validações dos modelos continuam lançando uma subclasse de `TypeError`
-(`ErroValidacaoModelo`). Por exemplo, uma data com fuso em `TNFe.Ide.dEmi`
-informa `DATA_HORA_INVALIDA`, o campo e a orientação de usar a data/hora civil
-da UF em `AAAA-MM-DDTHH:mm:ss`, sem `Z` ou offset. Nenhum valor informado é
-incluído no diagnóstico. Uma chave desconhecida aponta o grupo conhecido,
-evitando registrar chaves que possam conter dados privados.
-
-`statusEnvio` refere-se à operação atual:
-
-| Status | Significado |
-| --- | --- |
-| `nao_enviado` | Etapa local confirmada ou falha comprovadamente anterior ao envio desta operação. Não prova ausência de envios anteriores. |
-| `rejeitado` | Resultado fiscal de rejeição ou denegação; confira `cStat` e a orientação. |
-| `autorizado` | Autorização confirmada com identidade/protocolo; em eventos, a mensagem identifica cancelamento, registro ou inutilização. |
-| `resultado_incerto` | Resultado pendente, evidência incompleta/contraditória ou interrupção após possível envio. Consulte antes de repetir. |
-
-Os campos e os estados anteriores da API permanecem disponíveis. O XML de
-recuperação de `ErroAcbrNode` ainda pode ser lido explicitamente em `xmlBase64`,
-mas não é enumerável; `JSON.stringify(erro)` devolve apenas o diagnóstico
-sanitizado. `cause` contém somente código, etapa e campo conhecidos. Nenhum
-helper retransmite ou altera o resultado fiscal.
-
-O encerramento de um filho fiscal iniciado aguarda `close` por até 1000 ms após
-o pedido de parada. Se `kill` falha ou o filho não confirma o encerramento, a
-operação termina com seu erro original e um aviso adicional em
-`diagnostico.limpeza`, com código `ENCERRAMENTO_MOTOR_NAO_CONFIRMADO` e etapa
-`limpeza`. O supervisor libera somente os pipes e handles desse filho,
-bloqueia a fila e novas operações do emissor e não afirma que o processo
-terminou. Encerre a aplicação antes de iniciar outro motor; se havia envio
-possível, consulte a situação fiscal antes de repetir. Chamadas concorrentes
-de `fechar()` aguardam o mesmo encerramento limitado. O watcher nativo
-acompanha o processo pai e encerra o filho quando o pai termina.
-
-## Processo auxiliar
-
-Protocolo JSONL versão 1 em stdin/stdout. Certificado e senha são enviados pelas pipes, nunca como argumentos. O ambiente herdado é restrito a variáveis de sistema; stderr bruto não é apresentado como erro público. Limites de mensagem, timeout, checks de hash e validações de identidade protegem a comunicação. O processo acompanha o PID do pai e termina quando o pai encerra.
-
-Cada pedido tem `id`, `versao`, `sourceRevision`, `contractHash`, `comando`, `config` e parâmetros da operação. Antes de enviar uma operação com efeitos fiscais, o motor escreve `{ tipo: "envioIniciado", id }`. A resposta final precisa repetir identidade e contrato. O supervisor aguarda o fechamento do processo antes de liberar a próxima operação.
-
-TLS usa OpenSSL com verificação de cadeia, validade, finalidade e hostname antes de enviar bytes de aplicação. No Linux usa as CAs do sistema; no Windows exporta raízes públicas confiáveis para um bundle temporário. Esta versão não implementa consulta de revogação CRL/OCSP.
+# API e protocolo
+
+`criarEmissor` retorna operações assíncronas; cada chamada inicia um processo fiscal isolado. Uma instância processa uma operação por vez, com fila limitada. Emitentes diferentes não compartilham o componente Pascal.
+
+## Configuração
+
+Campos obrigatórios: `cnpj` (14 dígitos), `uf`, `modelo` (55/65), `ambiente` (1 produção, 2 homologação). Certificado A1: `certificado: { pfx: Uint8Array, senha: string }` ou `{ arquivo: string, senha: string }`. NFC-e requer `csc: { id: string, valor: string }` para os recursos que dependem do CSC.
+
+`timeoutMs` tem padrão/máximo de 120.000 ms; `limiteFila` tem padrão 32. `runtimeDirectory` seleciona um runtime próprio cujo contrato deve coincidir com o cliente. Cada operação aceita `{ signal: AbortSignal }` como último argumento. `fechar()` cancela a fila, encerra e aguarda o processo em execução.
+
+Com `limiteFila: 0`, uma operação pode executar e chamadas concorrentes recebem
+`FILA_CHEIA`. Após o `await` dessa operação, a fila já está disponível para a
+próxima chamada; isso também vale quando a operação termina com erro, salvo
+quando o emissor foi fechado ou o encerramento do motor não foi confirmado.
+
+## Operações
+
+| Método | Entrada |
+| --- | --- |
+| `gerarXml` | Objeto TNFe/TNFeInput com nomes ACBr |
+| `assinar`, `validar`, `transmitir` | XML UTF-8 como string |
+| `consultar` | `{ chave, recibo? }` |
+| `recuperarXml` | XML UTF-8 de uma única NFe 4.00 já assinada; faz uma consulta externa pela chave do XML |
+| `cancelar` | `{ chave, protocolo, justificativa }` |
+| `cartaCorrecao` | `{ chave, correcao, sequenciaEvento? }`; modelo 55 |
+| `inutilizar` | `{ ano, serie, numeroInicial, numeroFinal, justificativa }`; ano com 2 dígitos |
+
+A resposta `ResultadoFiscal` contém `sucesso`, `estado`, revisão/hash do contrato e, quando disponíveis, `cStat`, `xMotivo`, `chave`, `protocolo`, `recibo` e `xmlBase64`. `sucesso` deve ser conferido antes de usar o resultado. XML é devolvido em base64 para preservar os bytes UTF-8.
+
+Rejeições fiscais e recibos pendentes são resultados, sem retry automático. Falhas no supervisor lançam `ErroAcbrNode` com `codigo` e `resultadoDesconhecido`. Em falha/timeout de uma operação que pode ter iniciado envio, consulte a situação fiscal antes de decidir uma nova transmissão. O erro de transmissão conserva `xmlBase64` para recuperação.
+
+## Consulta e recuperação do XML
+
+As duas operações têm contratos distintos e não compartilham uma coleção nativa de notas entre chamadas:
+
+| Operação | Entrada e saída |
+| --- | --- |
+| `consultar({ chave })` | Consulta a situação. `xmlBase64`, quando presente, contém o retorno do serviço (`retConsSitNFe`), não o arquivo original da NFe. O comportamento anterior permanece disponível. |
+| `recuperarXml(xmlAssinado, opcoes?)` | Recebe o original assinado e retorna `Promise<ResultadoFiscal>`. Usa uma nova consulta para obter o protocolo e devolver o `nfeProc` completo, somente quando a recuperação foi comprovada. |
+
+O segundo argumento, `opcoes?: OpcoesOperacao`, é opcional: pode ser omitido, como em `emissor.recuperarXml(xmlAssinado)`. `OpcoesOperacao` aceita somente `signal?: AbortSignal`. Para permitir um pedido de cancelamento, passe `{ signal: controlador.signal }`, obtido de um `AbortController`, e chame `controlador.abort()` quando necessário. O sinal solicita o cancelamento da operação do SDK; não cancela a autorização fiscal. A consulta pode já ter sido enviada quando o sinal é acionado.
+
+A operação exige A1 para a consulta e XML de uma única NFe 4.00, sem envelope, DTD ou entidades externas. A chave é derivada do documento, não de um parâmetro separado. O motor valida o schema e a assinatura da NFe de entrada antes da consulta e confere emitente, UF, modelo e ambiente contra a configuração do emissor.
+
+O sucesso exige cumulativamente `sucesso=true`, `estado='XML_RECUPERADO'`, `cStat=100` e `xmlBase64` contendo o processo completo. O protocolo deve ter 15 dígitos, pertencer à mesma chave e ambiente e vir da resposta desta consulta. O `digVal` do protocolo é obrigatório e precisa ser exatamente igual ao `DigestValue` da referência assinada da NFe verificada; a comparação de base64 diferencia maiúsculas de minúsculas. O motor preserva o corpo da NFe e sua assinatura original, compõe com o protocolo recebido, valida o schema do processo resultante e verifica novamente a assinatura da NFe. Não reconstrói um protocolo a partir apenas dos campos escalares.
+
+Na versão 0.2.0, um `protNFe` com assinatura XMLDSig (`ds:Signature`) é recusado com `RECUPERACAO_NAO_COMPROVADA`, sem `xmlBase64` ou `protocolo`, independentemente da validade dessa assinatura e mesmo quando o status é `100`. O verificador disponível nesta versão não comprova de forma independente essa assinatura adicional da SEFAZ; mudanças no contexto de namespaces do envelope também podem afetar a canonicalização. A operação não oferece preservação ou verificação de uma assinatura do protocolo. A assinatura original da NFe é preservada e verificada antes e depois da composição. Os protocolos aceitos mantêm os dados da resposta real e exigem a correlação por `digVal` descrita acima.
+
+Para status diferente de `100`, inclusive `150` e `217`, a nova operação devolve `sucesso=false`, estado `CONSULTADO`, código `RECUPERACAO_NAO_COMPROVADA` e o `cStat`/motivo recebido, sem `protocolo` ou `xmlBase64` de recuperação. Uma resposta `100` incompleta ou divergente também falha, sem XML ou protocolo, com o diagnóstico correspondente: divergências de chave, ambiente ou digest usam `IDENTIDADE_DIVERGENTE`; falhas de schema usam `XML_SCHEMA_INVALIDO`. Isso não altera os estados e resultados de `consultar`, inclusive seu tratamento anterior de `150`. O diagnóstico sanitizado de uma recuperação concluída usa `XML_RECUPERADO` e explica que a autorização foi consultada, sem nova transmissão.
+
+Essa consulta é uma operação de rede. `envioIniciado=false` informa que não se iniciou transmissão de nota ou evento; não informa que a operação foi offline. A recuperação não chama `assinar`, `transmitir`, eventos ou inutilização, não tenta emitir novamente e não persiste nem substitui arquivos fiscais. A aplicação decide onde salvar os bytes devolvidos e deve preservar o arquivo assinado original. O exemplo em [examples/recuperar-xml.mjs](examples/recuperar-xml.mjs) deixa essa gravação para o chamador e não inicia consulta ao ser importado.
+
+Atualize SDK e runtime da plataforma em conjunto. Para essa operação, o manifesto precisa incluir `capabilities: ['recuperarXml']`, além dos demais campos e hashes. Um motor sem essa capacidade é recusado com `RUNTIME_SEM_CAPACIDADE` antes de iniciar o processo; não basta reaproveitar um binário antigo com o mesmo contrato dos modelos. A adição mantém a versão 1 do protocolo JSONL e não muda `consultar`.
+
+`validar(xml)` continua recebendo uma NFe sem envelope. Para verificar um `nfeProc` recebido ou salvo pela aplicação, use seu schema de processo (`procNFe_v4.00.xsd`), não `validar(nfeProc)`. Na recuperação, a validação do processo e a conferência da assinatura original da NFe já são responsabilidade do motor, com a limitação sobre assinatura adicional do protocolo descrita acima.
+
+## Feedback seguro para o usuário
+
+Os resultados incluem `diagnostico`, com `codigo`, `etapa`, `mensagem`, `acao`,
+`statusEnvio` e, quando disponíveis, `campo` e `cStat`. Também estão disponíveis
+os helpers `diagnosticarErro(erro)` e `diagnosticarResultado(resultado, comando)`.
+Use esse resumo nas interfaces e nos logs. Ele não copia XML, identidade fiscal,
+caminhos, senha, `xMotivo`, stderr, stack ou causa bruta.
+
+```ts
+import { TNFe, diagnosticarErro, diagnosticarResultado } from 'cosmemilton-acbr-node';
+
+try {
+  const resultado = await emissor.gerarXml(new TNFe(dados));
+  const d = resultado.diagnostico ?? diagnosticarResultado(resultado, 'gerarXml');
+  mostrarAoUsuario(d); // Apresente mensagem, campo, ação e statusEnvio.
+} catch (erro) {
+  mostrarAoUsuario(diagnosticarErro(erro)); // Não registre o erro bruto.
+}
+```
+
+As validações dos modelos continuam lançando uma subclasse de `TypeError`
+(`ErroValidacaoModelo`). Por exemplo, uma data com fuso em `TNFe.Ide.dEmi`
+informa `DATA_HORA_INVALIDA`, o campo e a orientação de usar a data/hora civil
+da UF em `AAAA-MM-DDTHH:mm:ss`, sem `Z` ou offset. Nenhum valor informado é
+incluído no diagnóstico. Uma chave desconhecida aponta o grupo conhecido,
+evitando registrar chaves que possam conter dados privados.
+
+`statusEnvio` refere-se à operação atual:
+
+| Status | Significado |
+| --- | --- |
+| `nao_enviado` | Etapa local confirmada ou falha comprovadamente anterior ao envio desta operação. Não prova ausência de envios anteriores. |
+| `rejeitado` | Resultado fiscal de rejeição ou denegação; confira `cStat` e a orientação. |
+| `autorizado` | Autorização confirmada com identidade/protocolo; em eventos, a mensagem identifica cancelamento, registro ou inutilização. |
+| `resultado_incerto` | Resultado pendente, evidência incompleta/contraditória ou interrupção após possível envio. Consulte antes de repetir. |
+
+Os campos e os estados anteriores da API permanecem disponíveis. O XML de
+recuperação de `ErroAcbrNode` ainda pode ser lido explicitamente em `xmlBase64`,
+mas não é enumerável; `JSON.stringify(erro)` devolve apenas o diagnóstico
+sanitizado. `cause` contém somente código, etapa e campo conhecidos. Nenhum
+helper retransmite ou altera o resultado fiscal.
+
+O encerramento de um filho fiscal iniciado aguarda `close` por até 1000 ms após
+o pedido de parada. Se `kill` falha ou o filho não confirma o encerramento, a
+operação termina com seu erro original e um aviso adicional em
+`diagnostico.limpeza`, com código `ENCERRAMENTO_MOTOR_NAO_CONFIRMADO` e etapa
+`limpeza`. O supervisor libera somente os pipes e handles desse filho,
+bloqueia a fila e novas operações do emissor e não afirma que o processo
+terminou. Encerre a aplicação antes de iniciar outro motor; se havia envio
+possível, consulte a situação fiscal antes de repetir. Chamadas concorrentes
+de `fechar()` aguardam o mesmo encerramento limitado. O watcher nativo
+acompanha o processo pai e encerra o filho quando o pai termina.
+
+## Processo auxiliar
+
+Protocolo JSONL versão 1 em stdin/stdout. Certificado e senha são enviados pelas pipes, nunca como argumentos. O ambiente herdado é restrito a variáveis de sistema; stderr bruto não é apresentado como erro público. Limites de mensagem, timeout, checks de hash e validações de identidade protegem a comunicação. O processo acompanha o PID do pai e termina quando o pai encerra.
+
+Cada pedido tem `id`, `versao`, `sourceRevision`, `contractHash`, `comando`, `config` e parâmetros da operação. Antes de enviar uma operação com efeitos fiscais, o motor escreve `{ tipo: "envioIniciado", id }`. A resposta final precisa repetir identidade e contrato. O supervisor aguarda o fechamento do processo antes de liberar a próxima operação.
+
+TLS usa OpenSSL com verificação de cadeia, validade, finalidade e hostname antes de enviar bytes de aplicação. No Linux usa as CAs do sistema; no Windows exporta raízes públicas confiáveis para um bundle temporário. Esta versão não implementa consulta de revogação CRL/OCSP.

package/docs/ARQUITETURA.md

@@ -1,15 +1,19 @@
-# Arquitetura
-
-O projeto contém quatro partes: cliente TypeScript (`src/runtime.ts`), CLI (`src/cli.ts`), extractor FCL-passrc (`tools/extract-model.lpr`) e motor `TACBrNFe` (`native/acbr-worker.lpr`).
-
-1. SVN resolve uma revisão explícita ou HEAD e exporta os componentes públicos necessários. A revisão exata e hashes de todos os arquivos ficam no lock.
-2. FCL-passrc analisa unidades Pascal com includes e condicionais. A resolução alcança herança, aliases, propriedades, campos públicos e coleções do modelo TNFe.
-3. A representação intermediária única gera classes/inputs/enums/validadores TypeScript e loaders Pascal. O relatório de compatibilidade compara contratos anteriores.
-4. FPC compila os loaders junto do motor fiscal. Schemas, serviços e dependências seguem a revisão travada; o runtime recebe manifesto com hashes.
-5. Node verifica arquivos, revisão e contrato, envia uma operação JSONL por processo e entrega o resultado assíncrono.
-
-Não há FFI nem addon vinculado a uma versão específica do ABI do Node. As duas plataformas usam o mesmo protocolo e modelos. Recursos que antes exigiam APIs Windows, como confiança TLS e lifecycle do processo, possuem implementação específica por plataforma.
-
-O código do Integrador existente não foi alterado ou incorporado como dependência. Regras comerciais, persistência, impostos e orquestração do documento continuam no aplicativo consumidor.
-
-Uma release principal contém ESM, CommonJS, declarações, fontes do extractor/motor, lock e documentos. Os pacotes `cosmemilton-acbr-node-linux-x64` e `cosmemilton-acbr-node-win32-x64` incluem runtime, fontes fiscais correspondentes, licenças e instruções de reconstrução. Gerar uma revisão própria exige SVN, Free Pascal e Lazarus gratuitos; consumir a release pronta exige apenas Node e a plataforma suportada.
+# Arquitetura
+
+O projeto contém quatro partes: cliente TypeScript (`src/runtime.ts`), CLI (`src/cli.ts`), extractor FCL-passrc (`tools/extract-model.lpr`) e motor `TACBrNFe` (`native/acbr-worker.lpr`).
+
+1. SVN resolve uma revisão explícita ou HEAD e exporta os componentes públicos necessários. A revisão exata e hashes de todos os arquivos ficam no lock.
+2. FCL-passrc analisa unidades Pascal com includes e condicionais. A resolução alcança herança, aliases, propriedades, campos públicos e coleções do modelo TNFe.
+3. A representação intermediária única gera classes/inputs/enums/validadores TypeScript e loaders Pascal. O relatório de compatibilidade compara contratos anteriores.
+4. FPC compila os loaders junto do motor fiscal. Schemas, serviços e dependências seguem a revisão travada; o runtime recebe manifesto com hashes.
+5. Node verifica arquivos, revisão e contrato, envia uma operação JSONL por processo e entrega o resultado assíncrono.
+
+Não há FFI nem addon vinculado a uma versão específica do ABI do Node. As duas plataformas usam o mesmo protocolo e modelos. Recursos que antes exigiam APIs Windows, como confiança TLS e lifecycle do processo, possuem implementação específica por plataforma.
+
+O código do Integrador existente não foi alterado ou incorporado como dependência. Regras comerciais, persistência, impostos e orquestração do documento continuam no aplicativo consumidor.
+
+`consultar` entrega o retorno do serviço. `recuperarXml` é um comando adicional: carrega uma NFe assinada, valida documento, assinatura e identidade da NFe original, consulta a chave e correlaciona o protocolo recebido, incluindo o digest obrigatório. Somente a recuperação que atende aos critérios documentados com `cStat=100` produz `XML_RECUPERADO` e o `nfeProc`, preservando o conteúdo assinado; não há nova emissão, assinatura ou persistência fiscal automática. O supervisor exige a capacidade `recuperarXml` no manifesto antes de iniciar esse comando, para não encaminhá-lo a motores antigos. Uma chamada anterior a `validar` não carrega notas para uma chamada seguinte: cada operação usa seu próprio processo fiscal.
+
+Na versão 0.2.0, `protNFe` com assinatura XMLDSig (`ds:Signature`) é recusado com `RECUPERACAO_NAO_COMPROVADA`, sem XML ou protocolo no resultado. O verificador do ACBr fixado nesta versão resolve `SignedInfo` globalmente e não comprova de forma independente as duas assinaturas em um mesmo processo. O contexto de namespaces do envelope também pode alterar a canonicalização (C14N). A recuperação, portanto, não oferece preservação ou verificação da assinatura adicional da SEFAZ no protocolo. Para os protocolos aceitos, usa os dados da resposta real e exige `digVal` exatamente igual ao digest assinado. A assinatura original da NFe é preservada e verificada antes da consulta e depois da composição do `nfeProc`.
+
+Uma release principal contém ESM, CommonJS, declarações, fontes do extractor/motor, lock e documentos. Os pacotes `cosmemilton-acbr-node-linux-x64` e `cosmemilton-acbr-node-win32-x64` incluem runtime, fontes fiscais correspondentes, licenças e instruções de reconstrução. Gerar uma revisão própria exige SVN, Free Pascal e Lazarus gratuitos; consumir a release pronta exige apenas Node e a plataforma suportada.

package/docs/CI.md

@@ -1,60 +1,60 @@
-# Validação e preparação npm
-
-Os workflows de validação são acionados manualmente e não publicam no npm. O workflow `publish.yml` publica os tarballs revisados quando há um push na branch `release`; o acionamento manual também exige essa branch. Nenhum workflow transmite à SEFAZ. A revisão ACBr é entrada explícita, registrada no lock e nos manifestos. Os testes fiscais usam respostas locais simuladas e certificados sintéticos; a homologação fiscal continua separada.
-
-## Linux
-
-`validate-linux.yml` usa Ubuntu24.04, Node24 e pacotes livres FPC3.2.2/Lazarus3.0. Gera e compila o cliente/motor, verifica hashes, executa testes e instala tarballs em consumidor externo ao repositório. A revisão própria desse consumidor é outra entrada. O diretório padrão fica em `~/.acbr-node-validation/consumer-REV`; uma pasta já existente precisa ser preservada e outro `--directory` selecionado.
-
-## Windows
-
-`validate-windows.yml` primeiro compila OpenSSL/libxml2 no Ubuntu com MinGW, usando arquivos oficiais fixados por SHA256 em `build-native-deps.mjs`. Transfere DLLs, notices e proveniência como artifact. O segundo job usa um runner próprio Windows x64 com label `acbr-toolchain`; a preparação do runner é manual e ainda precisa ser validada ao instalar esse workflow no repositório remoto.
-
-Instale Free Pascal3.2.2 x64 e Lazarus com LCL/LazUtils compilados pelo [download oficial Free Pascal](https://www.freepascal.org/download.html) e pelos [downloads oficiais Lazarus](https://www.lazarus-ide.org/index.php?page=downloads). Instale SVN e tar no PATH do runner. O Windows moderno oferece `tar.exe`; confira antes do job. As ferramentas e o compilador são gratuitos. Nenhum instalador é baixado por URL não verificada e nenhuma action de terceiros configura Pascal.
-
-Configure as variáveis do repositório `FPC_ROOT` (raiz da instalação3.2.2, contendo `bin/x86_64-win64/ppcx64.exe` e `fpcmkcfg.exe`) e `LAZARUS_ROOT` (raiz contendo `components/lazutils`, `lcl/units` e as unidades x64). A instalação deve conter RTL/FCL, unidades de rede e fontes/licenças. A receita Windows local foi validada com FPC3.2.2/Lazarus4.8; Linux com Lazarus3.0.
-
-`prepare-windows-build.ps1` cria um `fpc.cfg` exclusivo em `.acbr/fpc/windows`, define `PPC_CONFIG_PATH` e escreve `acbr.ci.windows.config.json`. A configuração original e a instalação do compilador são preservadas. Para executar a mesma preparação localmente, com as dependências já compiladas:
-
-```powershell
-$env:FPC_ROOT = 'C:\Ferramentas\lazarus\fpc\3.2.2'
-$env:LAZARUS_ROOT = 'C:\Ferramentas\lazarus'
-./scripts/prepare-windows-build.ps1 -Revision 48590
-npm ci --omit=optional
-npm run build:cli
-node dist/cli.js --config acbr.ci.windows.config.json source update --revision 48590
-node dist/cli.js --config acbr.ci.windows.config.json generate
-npm run build
-node dist/cli.js --config acbr.ci.windows.config.json build
-node dist/cli.js --config acbr.ci.windows.config.json check
-```
-
-## Gate de publicação
-
-Depois de validar os dois sistemas, use `npm run build`, `node scripts/pack-runtimes.mjs --all` e `node scripts/publish-artifacts.mjs`. O último comando prepara os três tarballs e executa somente `npm publish --dry-run`. Confere hashes dos três arquivos gerados e de cada arquivo runtime, revisão/contrato, fontes do motor correspondentes ao pacote principal, licenças, schemas, proveniência das DLLs e ausência de arquivos pessoais no pacote principal. Recusa binários de teste e arquivos fora do manifesto. Todos os pacotes são auditados e empacotados antes da primeira operação de publicação.
-
-A publicação exige autenticação npm válida e a opção explícita `--publish`. A autenticação é conferida antes do primeiro pacote. Publique primeiro os dois runtimes e depois o pacote principal; o script mantém essa ordem. Nunca coloque token npm no repositório, configuração de build ou tarballs. Os artifacts de Linux e Windows continuam sujeitos à mesma auditoria local antes de publicar uma versão conjunta.
-
-## Publicação automática de artefatos revisados
-
-A publicação npm foi autorizada pelo usuário em **09/10/2026**. O workflow `.github/workflows/publish.yml` usa o secret GitHub `NPM_TOKEN` somente no passo de publicação. O token precisa permitir publicação pública dos três pacotes. Seu valor não pertence ao repositório, aos manifests ou aos tarballs.
-
-A automação publica os artefatos prontos; a compilação dos motores e a revisão dos testes acontecem antes de preparar uma nova versão. Depois das validações Linux/Windows e da autorização para publicar, prepare e fixe os hashes:
-
-```bash
-npm run release:prepare
-node scripts/prepare-npm-release.mjs --authorized-on AAAA-MM-DD
-node scripts/npm-release-bundle.mjs --dry-run .acbr/release-artifacts
-```
-
-Envie os três `.tgz`, `SHA256SUMS` e `VALIDATION.json` de `.acbr/release-artifacts` para `https://miltonjunior.dev.br/acbr-node/releases/<versão>/`. Preserve esses assets por versão. Versione somente `.github/npm-release.json` e os documentos em `release/<versão>/`; os binários não vão para o git. Depois envie a alteração revisada à branch `release`.
-
-O runner usa HTTPS com verificação de certificado/hostname e recusa redirecionamentos. Confere os downloads contra hashes fixados no git, lê os metadados npm dos tarballs, audita inventários/fontes/licenças e executa um dry run antes de disponibilizar o token ao passo de publicação npm. Não recompila os motores nesse processo.
-
-A ordem é Linux, Windows e SDK. Antes de publicar qualquer pacote ausente, o script compara os hashes npm de todas as versões que já existem. Uma reexecução pula somente tarballs idênticos e continua uma publicação parcial. Qualquer versão existente com conteúdo diferente interrompe a operação; publique uma nova versão depois de revisar a diferença. A fila de workflows impede duas publicações simultâneas.
-
-O dry run também confere primeiro os hashes das versões públicas e pula somente as idênticas, porque o npm recusa repetir uma versão mesmo com `--dry-run`. Quando um envio retorna sucesso, a confirmação consulta o registro ou staging por cerca de nove minutos, além do tempo das consultas, sem repetir o envio. Essa janela cobre o atraso observado nas primeiras publicações Linux/Windows da versão 0.1.0. O workflow permite até 45 minutos para confirmar os três pacotes.
-
-O npm também pode manter uma versão em staging, aguardando aprovação com 2FA. Antes de enviar qualquer pacote, a automação consulta os estágios dos três nomes, verifica identidade, versão, tag `latest` e SHA-1 e baixa os tarballs pendentes em diretórios temporários para conferir os bytes contra os aprovados. Uma versão pendente idêntica é preservada e não é enviada novamente. Um conflito interrompe a execução antes de novas publicações. Quando o npm recusa publicação direta com `E_STAGE_REQUIRED`, a automação envia somente o mesmo tarball aprovado para staging. Se algum runtime estiver pendente, o SDK também é enviado a staging, evitando disponibilizar o cliente antes dos motores.
-
-O resultado `awaiting-2fa` indica que a versão ainda não está disponível para instalação. O resumo do workflow e o artifact `npm-publication-result` registram os identificadores e os hashes conferidos. O mantenedor deve aprovar os estágios em `npmjs.com`, na aba **Staged Packages**, ou executar `npm stage approve <identificador>` em uma sessão npm local autenticada. Essa confirmação com 2FA é exigida pelo npm; o workflow não altera a política de publicação ou autenticação. Aprove primeiro os runtimes Linux/Windows e depois o SDK, e reexecute o workflow para confirmar os hashes públicos dos três pacotes. [Fluxo oficial de staging npm](https://docs.npmjs.com/staged-publishing/).
+# Validação e preparação npm
+
+Os workflows de validação são acionados manualmente e não publicam no npm. O workflow `publish.yml` publica os tarballs revisados quando há um push na branch `release`; o acionamento manual também exige essa branch. Nenhum workflow transmite à SEFAZ. A revisão ACBr é entrada explícita, registrada no lock e nos manifestos. Os testes fiscais usam respostas locais simuladas e certificados sintéticos; a homologação fiscal continua separada.
+
+## Linux
+
+`validate-linux.yml` usa Ubuntu24.04, Node24 e pacotes livres FPC3.2.2/Lazarus3.0. Gera e compila o cliente/motor, verifica hashes, executa testes e instala tarballs em consumidor externo ao repositório. A revisão própria desse consumidor é outra entrada. O diretório padrão fica em `~/.acbr-node-validation/consumer-REV`; uma pasta já existente precisa ser preservada e outro `--directory` selecionado.
+
+## Windows
+
+`validate-windows.yml` primeiro compila OpenSSL/libxml2 no Ubuntu com MinGW, usando arquivos oficiais fixados por SHA256 em `build-native-deps.mjs`. Transfere DLLs, notices e proveniência como artifact. O segundo job usa um runner próprio Windows x64 com label `acbr-toolchain`; a preparação do runner é manual e ainda precisa ser validada ao instalar esse workflow no repositório remoto.
+
+Instale Free Pascal3.2.2 x64 e Lazarus com LCL/LazUtils compilados pelo [download oficial Free Pascal](https://www.freepascal.org/download.html) e pelos [downloads oficiais Lazarus](https://www.lazarus-ide.org/index.php?page=downloads). Instale SVN e tar no PATH do runner. O Windows moderno oferece `tar.exe`; confira antes do job. As ferramentas e o compilador são gratuitos. Nenhum instalador é baixado por URL não verificada e nenhuma action de terceiros configura Pascal.
+
+Configure as variáveis do repositório `FPC_ROOT` (raiz da instalação3.2.2, contendo `bin/x86_64-win64/ppcx64.exe` e `fpcmkcfg.exe`) e `LAZARUS_ROOT` (raiz contendo `components/lazutils`, `lcl/units` e as unidades x64). A instalação deve conter RTL/FCL, unidades de rede e fontes/licenças. A receita Windows local foi validada com FPC3.2.2/Lazarus4.8; Linux com Lazarus3.0.
+
+`prepare-windows-build.ps1` cria um `fpc.cfg` exclusivo em `.acbr/fpc/windows`, define `PPC_CONFIG_PATH` e escreve `acbr.ci.windows.config.json`. A configuração original e a instalação do compilador são preservadas. Para executar a mesma preparação localmente, com as dependências já compiladas:
+
+```powershell
+$env:FPC_ROOT = 'C:\Ferramentas\lazarus\fpc\3.2.2'
+$env:LAZARUS_ROOT = 'C:\Ferramentas\lazarus'
+./scripts/prepare-windows-build.ps1 -Revision 48590
+npm ci --omit=optional
+npm run build:cli
+node dist/cli.js --config acbr.ci.windows.config.json source update --revision 48590
+node dist/cli.js --config acbr.ci.windows.config.json generate
+npm run build
+node dist/cli.js --config acbr.ci.windows.config.json build
+node dist/cli.js --config acbr.ci.windows.config.json check
+```
+
+## Gate de publicação
+
+Depois de validar os dois sistemas, use `npm run build`, `node scripts/pack-runtimes.mjs --all` e `node scripts/publish-artifacts.mjs`. O último comando prepara os três tarballs e executa somente `npm publish --dry-run`. Confere hashes dos três arquivos gerados e de cada arquivo runtime, revisão/contrato, fontes do motor correspondentes ao pacote principal, licenças, schemas, proveniência das DLLs e ausência de arquivos pessoais no pacote principal. Recusa binários de teste e arquivos fora do manifesto. Todos os pacotes são auditados e empacotados antes da primeira operação de publicação.
+
+A publicação exige autenticação npm válida e a opção explícita `--publish`. A autenticação é conferida antes do primeiro pacote. Publique primeiro os dois runtimes e depois o pacote principal; o script mantém essa ordem. Nunca coloque token npm no repositório, configuração de build ou tarballs. Os artifacts de Linux e Windows continuam sujeitos à mesma auditoria local antes de publicar uma versão conjunta.
+
+## Publicação automática de artefatos revisados
+
+A publicação npm foi autorizada pelo usuário em **09/10/2026**. O workflow `.github/workflows/publish.yml` usa o secret GitHub `NPM_TOKEN` somente no passo de publicação. O token precisa permitir publicação pública dos três pacotes. Seu valor não pertence ao repositório, aos manifests ou aos tarballs.
+
+A automação publica os artefatos prontos; a compilação dos motores e a revisão dos testes acontecem antes de preparar uma nova versão. Depois das validações Linux/Windows e da autorização para publicar, prepare e fixe os hashes:
+
+```bash
+npm run release:prepare
+node scripts/prepare-npm-release.mjs --authorized-on AAAA-MM-DD
+node scripts/npm-release-bundle.mjs --dry-run .acbr/release-artifacts
+```
+
+Envie os três `.tgz`, `SHA256SUMS` e `VALIDATION.json` de `.acbr/release-artifacts` para `https://miltonjunior.dev.br/acbr-node/releases/<versão>/`. Preserve esses assets por versão. Versione somente `.github/npm-release.json` e os documentos em `release/<versão>/`; os binários não vão para o git. Depois envie a alteração revisada à branch `release`.
+
+O runner usa HTTPS com verificação de certificado/hostname e recusa redirecionamentos. Confere os downloads contra hashes fixados no git, lê os metadados npm dos tarballs, audita inventários/fontes/licenças e executa um dry run antes de disponibilizar o token ao passo de publicação npm. Não recompila os motores nesse processo.
+
+A ordem é Linux, Windows e SDK. Antes de publicar qualquer pacote ausente, o script compara os hashes npm de todas as versões que já existem. Uma reexecução pula somente tarballs idênticos e continua uma publicação parcial. Qualquer versão existente com conteúdo diferente interrompe a operação; publique uma nova versão depois de revisar a diferença. A fila de workflows impede duas publicações simultâneas.
+
+O dry run também confere primeiro os hashes das versões públicas e pula somente as idênticas, porque o npm recusa repetir uma versão mesmo com `--dry-run`. Quando um envio retorna sucesso, a confirmação consulta o registro ou staging por cerca de nove minutos, além do tempo das consultas, sem repetir o envio. Essa janela cobre o atraso observado nas primeiras publicações Linux/Windows da versão 0.1.0. O workflow permite até 45 minutos para confirmar os três pacotes.
+
+O npm também pode manter uma versão em staging, aguardando aprovação com 2FA. Antes de enviar qualquer pacote, a automação consulta os estágios dos três nomes, verifica identidade, versão, tag `latest` e SHA-1 e baixa os tarballs pendentes em diretórios temporários para conferir os bytes contra os aprovados. Uma versão pendente idêntica é preservada e não é enviada novamente. Um conflito interrompe a execução antes de novas publicações. Quando o npm recusa publicação direta com `E_STAGE_REQUIRED`, a automação envia somente o mesmo tarball aprovado para staging. Se algum runtime estiver pendente, o SDK também é enviado a staging, evitando disponibilizar o cliente antes dos motores.
+
+O resultado `awaiting-2fa` indica que a versão ainda não está disponível para instalação. O resumo do workflow e o artifact `npm-publication-result` registram os identificadores e os hashes conferidos. O mantenedor deve aprovar os estágios em `npmjs.com`, na aba **Staged Packages**, ou executar `npm stage approve <identificador>` em uma sessão npm local autenticada. Essa confirmação com 2FA é exigida pelo npm; o workflow não altera a política de publicação ou autenticação. Aprove primeiro os runtimes Linux/Windows e depois o SDK, e reexecute o workflow para confirmar os hashes públicos dos três pacotes. [Fluxo oficial de staging npm](https://docs.npmjs.com/staged-publishing/).

package/docs/CLI.md

@@ -2,7 +2,7 @@
 
 ## Help de tipos e campos — implementação de desenvolvimento
 
-O help TAG faz parte da release 0.1.2. A documentação pública só anuncia disponibilidade após a confirmação dessa versão no registry npm.
+O help TAG foi introduzido na release 0.1.2 e permanece na 0.2.0 descrita nesta documentação. A disponibilidade da 0.2.0 no npm só é anunciada após a confirmação dessa versão no registry.
 
 ```sh
 node dist/cli.js help TAG Ide.tpNF