cosmemilton-acbr-node 0.1.1 → 0.2.0

package/dist/types/src/contract-help.d.ts

@@ -0,0 +1,53 @@
+import type { ModelIR, ModelProperty } from './generator.js';
+export interface ContractMetadata {
+    formatVersion: 1;
+    sourceRevision: number;
+    sourceHash: string;
+    contractHash: string;
+    ir: ModelIR;
+}
+export interface FieldDescription {
+    formatVersion: 1;
+    sdkVersion: string;
+    sourceRevision: number;
+    sourceHash: string;
+    contractHash: string;
+    root: string;
+    path: string;
+    kind: ModelProperty['kind'];
+    pascalType: string;
+    typeReference?: string;
+    inputType: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    readonly: boolean;
+    declaredDefault?: string;
+    values?: string[];
+    constraints?: {
+        min?: number;
+        max?: number;
+        scale?: number;
+    };
+    itemType?: string;
+    members?: {
+        name: string;
+        kind: ModelProperty['kind'];
+        pascalType: string;
+        readonly: boolean;
+    }[];
+}
+export declare class FieldHelpError extends Error {
+    readonly code: string;
+    readonly details?: {
+        segment?: string;
+        ownerType?: string;
+        candidates?: string[];
+    } | undefined;
+    constructor(code: string, message: string, details?: {
+        segment?: string;
+        ownerType?: string;
+        candidates?: string[];
+    } | undefined);
+}
+export declare function validateContractMetadata(value: unknown): ContractMetadata;
+export declare function describeField(metadata: ContractMetadata, sdkVersion: string, query: string): FieldDescription;
+export declare function describeInstalledField(query: string, packageRoot: string): Promise<FieldDescription>;
+export declare function formatFieldDescription(description: FieldDescription): string;

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

@@ -1,4 +1,6 @@
 import { type Comando, type DetalhesErroAcbr, type DiagnosticoAcbr, type EtapaAcbr, type ResultadoFiscal } from './types.js';
+/** Limite do envelope recuperado; a entrada assinada mantém seu limite de 2 MiB. */
+export declare function base64XmlRecuperadoValido(value: unknown): value is string;
 export declare function etapaDaOperacao(comando: Comando): EtapaAcbr;
 /** Apenas catálogo e metadados conhecidos; nunca copia message, stack, stderr ou causa bruta. */
 export declare function criarDiagnosticoErro(codigo: string, desconhecido?: boolean, detalhes?: DetalhesErroAcbr): DiagnosticoAcbr;

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

@@ -82,6 +82,7 @@ export declare function compareContracts(previous: ModelIR | undefined, current:
 };
 export declare function renderModelValidation(): string;
 export declare function renderTypeScript(ir: ModelIR, revision: number, contractHash: string): string;
+export declare function renderContractMetadata(ir: ModelIR, sourceRevision: number, sourceHash: string, contractHash: string): string;
 export declare function renderPascal(ir: ModelIR, revision: number, contractHash: string): string;
 export declare function renderClientIndex(): string;
 export declare function generateModel(options: GenerateOptions): Promise<{
@@ -90,5 +91,6 @@ export declare function generateModel(options: GenerateOptions): Promise<{
     models: number;
     reportPath: string;
     manifestPath: string;
+    metadataPath: string;
 }>;
 export {};

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

@@ -2,7 +2,7 @@ import { type OpcoesEmissor, type OpcoesOperacao } from './runtime.js';
 import { type TNFeInput } from '../generated/acbr/models.js';
 export * from './runtime.js';
 export * from '../generated/acbr/models.js';
-export declare function diagnosticarErro(erro: unknown): import("./types.js").DiagnosticoAcbr | Readonly<{
+export declare function diagnosticarErro(erro: unknown): Readonly<{
     codigo: import("./index.js").CodigoValidacaoModelo;
     etapa: "documento";
     campo?: string;
@@ -14,13 +14,14 @@ export declare function diagnosticarErro(erro: unknown): import("./types.js").Di
         etapa: "documento";
         campo?: string;
     }>;
-}>;
+}> | import("./types.js").DiagnosticoAcbr;
 export type OpcoesCriarEmissor = Omit<OpcoesEmissor, 'contrato' | 'validaDocumento'>;
 export declare function criarEmissor(options: OpcoesCriarEmissor): {
     gerarXml(documento: TNFeInput, operacao?: OpcoesOperacao): Promise<import("./types.js").ResultadoFiscal>;
     validar: (xml: string, op?: OpcoesOperacao) => Promise<import("./types.js").ResultadoFiscal>;
     assinar: (xml: string, op?: OpcoesOperacao) => Promise<import("./types.js").ResultadoFiscal>;
     transmitir: (xml: string, op?: OpcoesOperacao) => Promise<import("./types.js").ResultadoFiscal>;
+    recuperarXml: (xmlAssinado: string, opcoes?: OpcoesOperacao) => Promise<import("./types.js").ResultadoFiscal>;
     consultar: (consulta: import("./types.js").Consulta, op?: OpcoesOperacao) => Promise<import("./types.js").ResultadoFiscal>;
     cancelar: (data: import("./types.js").Cancelamento, op?: OpcoesOperacao) => Promise<import("./types.js").ResultadoFiscal>;
     cartaCorrecao: (data: import("./types.js").CartaCorrecao, op?: OpcoesOperacao) => Promise<import("./types.js").ResultadoFiscal>;

package/dist/types/src/native-build.d.ts

@@ -10,6 +10,7 @@ export interface BuiltRuntimeManifest {
     systemDependencies?: string[];
     testOnly?: boolean;
     generatedFileHashes: Record<string, string>;
+    capabilities?: string[];
 }
 export declare function runtimeDirectory(config: AcbrConfig): string;
 export declare function findLazarus(config: AcbrConfig): Promise<string>;

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

@@ -18,6 +18,7 @@ export declare function criarEmissor(options: OpcoesEmissor): {
     validar: (xml: string, op?: OpcoesOperacao) => Promise<ResultadoFiscal>;
     assinar: (xml: string, op?: OpcoesOperacao) => Promise<ResultadoFiscal>;
     transmitir: (xml: string, op?: OpcoesOperacao) => Promise<ResultadoFiscal>;
+    recuperarXml: (xmlAssinado: string, opcoes?: OpcoesOperacao) => Promise<ResultadoFiscal>;
     consultar: (consulta: Consulta, op?: OpcoesOperacao) => Promise<ResultadoFiscal>;
     cancelar: (data: Cancelamento, op?: OpcoesOperacao) => Promise<ResultadoFiscal>;
     cartaCorrecao: (data: CartaCorrecao, op?: OpcoesOperacao) => Promise<ResultadoFiscal>;

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

@@ -20,6 +20,7 @@ quando o emissor foi fechado ou o encerramento do motor não foi confirmado.
 | `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 |
@@ -28,6 +29,31 @@ A resposta `ResultadoFiscal` contém `sucesso`, `estado`, revisão/hash do contr
 
 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`,

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

@@ -1,32 +1,52 @@
-# Fontes, contrato e build
-
-`init` cria a configuração e copia os fontes do motor e extractor distribuídos no pacote para o projeto do consumidor, preservando arquivos existentes. O CLI usa `acbr.config.json`. Todos os caminhos relativos são resolvidos pelo diretório desse arquivo, independentemente do diretório atual do terminal. Campos desconhecidos, revisão inválida ou outra origem SVN são rejeitados.
-
-```sh
-acbr-node init
-acbr-node source update
-acbr-node generate
-acbr-node build
-acbr-node check
-acbr-node doctor
-```
-
-`source update` é a única operação que busca alterações do SVN. Primeiro resolve `HEAD` para um número, exporta `Fontes`, schemas NF-e e licença para uma área temporária e registra a revisão e SHA256 de cada arquivo em `acbr.lock.json`. Se já houver fontes, precisa de um lock válido e recusa arquivos alterados, adicionados ou removidos. A geração, compilação e execução não atualizam fontes automaticamente.
-
-`source update` sem `--revision` consulta a revisão mais recente (`HEAD`), mesmo quando a configuração registra uma revisão anterior. `source update --revision 48590` seleciona explicitamente uma revisão. Após download e lock bem-sucedidos, o CLI persiste a revisão numérica resolvida na configuração, preservando os caminhos e demais campos. Falhas restauram fontes e lock; nenhuma atualização acontece na execução normal. Um export previamente obtido e conferido pelo operador pode ser registrado com `source lock --revision 48590`; esse comando confia na origem declarada pelo operador e calcula os hashes locais, sem comparar o conteúdo com o SVN remoto.
-
-`generate` recria os tipos em `generated/acbr/models.ts`, o mapper Pascal em `native/generated/AcbrModels.pas` e os manifestos/relatórios em `.acbr/generated`. Revise o relatório após cada atualização para detectar campos novos, removidos, enums e partes que o gerador não suporta.
-
-`build` confere fontes/contrato antes de invocar o Free Pascal. Usa os defines `NOGUI` e `NOREPORT`, unidades Lazarus sem interface gráfica, ACBr original e mapper gerado. Linux x64 e Windows x64 são os alvos iniciais. A compilação precisa ocorrer no sistema do alvo; não há cross-compilation implícita.
-
-No Linux, instale Free Pascal 3.2.2, Lazarus 3.0, SVN, OpenSSL 3, libxml2, tar/gzip e certificados CA do sistema. `native.lazarusRoot` ou `LAZARUS_ROOT` podem indicar outra instalação. O staging copia OpenSSL/libxml2 e suas dependências transitivas como bibliotecas dinâmicas com suas licenças e origem/versionamento dos pacotes fonte. Inclui o provider legacy e configuração de providers OpenSSL. glibc e o loader permanecem requisitos do sistema. O Linux usa glibc: o runtime não equivale a um binário portátil para qualquer distribuição ou Alpine.
-
-No Windows, configure `native.lazarusRoot`, `native.fpc`, `native.providerFiles` (incluindo `legacy.dll`) e `native.libraryFiles` para as DLLs x64 de TLS/XML. Cada DLL exige um arquivo de licença adjacente `<DLL>.LICENSE`; `<DLL>.SOURCE.json` registra opcionalmente origem e versão do código correspondente e é incluído na proveniência do runtime. As dependências também podem ser compiladas no WSL com MinGW, conforme [Dependências nativas](DEPENDENCIAS-NATIVAS.md). O motor Pascal é compilado no Windows pelo CLI; a compilação não substitui a homologação fiscal. A [receita de CI](CI.md) documenta instalação oficial gratuita, `FPC_ROOT`/`LAZARUS_ROOT` e criação de um `fpc.cfg` exclusivo com `PPC_CONFIG_PATH`, sem alterar a instalação do compilador.
-
-No Windows, execute comandos `npm` em uma pasta local, por exemplo `C:\Projetos\MinhaAplicacao`. O launcher `npm.cmd` usa `cmd.exe`, que não mantém um caminho UNC como diretório atual. Para trabalhar com um checkout WSL acessado por `\\wsl.localhost\...`, execute a CLI por `node caminho\dist\cli.js` e, quando necessário, invoque `npm-cli.js` diretamente por Node, indicando o caminho da instalação. Na compilação Pascal, fontes em uma pasta Windows local evitam o custo de leitura por UNC; `source.directory` pode apontar para essa cópia e o lock confere os mesmos hashes.
-
-O runtime fica em `.acbr/runtime/<platform>-<arch>`, contendo executável, bibliotecas dinâmicas, schemas, serviços NF-e, licenças, fontes correspondentes e `manifest.json`. O manifesto registra revisão ACBr, contrato, plataforma e SHA256 de cada arquivo. `check` verifica todos esses vínculos e arquivos e depois inicia o motor real em quatro probes locais: gera uma NF-e55 sintética para conferir mapper/chave/UTF-8, valida uma fixture XML assinada com certificado público sintético e recusa XML malformado e DTD/entidade externa. O smoke não recebe PFX, chave privada ou senha e não transmite documentos; `--json` inclui `offlineChecks`. A fixture assinada fica embutida no CLI, pois o schema exige `Signature` e o XML gerado sem A1 ainda não é assinado. O builder confere SHA256 dos três arquivos gerados antes e depois da compilação; uma alteração de mapper/helper invalida o build mesmo quando o hash do contrato permanece igual. O staging inclui notices FPC (GPL do compilador, LGPL e exceção da RTL), Lazarus e das bibliotecas dinâmicas, além da proveniência das cópias usadas. `doctor` informa ferramentas e dependências encontradas; ele não instala ferramentas nem transmite documentos.
-
-Atualizações concorrentes são recusadas com `acbr.lock.json.operation`. Se um processo encerrar abruptamente, confira o PID registrado antes de remover o marcador. Uma alteração de revisão durante a compilação invalida o resultado. O log FPC completo fica em `.acbr/build.log`.
-
-Use `--config caminho` para escolher a configuração e `--json` para obter saída estruturada. Nunca inclua senhas ou certificados nesse arquivo de build: a API recebe essas credenciais separadamente em memória.
+# Fontes, contrato e build
+
+## Help de tipos e campos — implementação de desenvolvimento
+
+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
+node dist/cli.js help TAG 'Det[].Imposto.PIS.CST' --json
+node dist/cli.js help TAG 'TNFe.Det[0].Prod.DI[].adi[2].nAdicao' --json
+```
+
+`Ide.tpNF` resolve para `TTipoNFe` e apresenta `tnEntrada` e `tnSaida`. O caminho PIS resolve para `TCSTPis`, com seus valores textuais, incluindo `pis99`. Os valores são obtidos do contrato gerado; não há catálogo de enums mantido manualmente.
+
+O prefixo `TNFe.` é opcional. Os nomes dos campos respeitam maiúsculas e minúsculas; `TAG` aceita ambas. `[]` consulta o tipo do elemento de uma coleção. Um índice não negativo, como `[0]`, é normalizado para `[]`: a consulta não lê uma nota nem confere a quantidade de itens. Um nome curto só é aceito quando identifica um caminho único; `CST` retorna `CAMPO_AMBIGUO` com os caminhos possíveis. `Det.Imposto` pede um seletor de coleção, enquanto `Ide[]` é recusado por não ser coleção.
+
+O help lê somente `dist/contract.json`, `package.json` e `acbr.lock.json` da própria instalação. Não consulta configuração do consumidor, runtime, certificado, SVN ou rede e funciona sem dependências opcionais. `--config` e `--revision` não se aplicam a esse comando. Saída JSON contém versão do SDK, revisão ACBr, hashes, caminho canônico, tipo, referências, valores, limites do tipo e indicação de somente leitura. Erros JSON vão para `stderr`, com código de saída 1; uma consulta válida termina com 0.
+
+Os caminhos pertencem ao modelo de entrada do SDK, não são XPath/XML. Por exemplo, o modelo usa `Ide.dEmi`; `Ide.dhEmi` é inexistente. `declaredDefault` é a declaração Pascal, não uma garantia sobre o construtor nativo. Limites primitivos, enums e campos opcionais do TypeScript não substituem regras fiscais, códigos XML, obrigatoriedade ou orientação tributária.
+
+`generate` também emite `generated/acbr/contract.json` a partir do mesmo IR usado pelo validador. O build confere o hash e o lock e distribui esses metadados em `dist/contract.json`, separados dos três arquivos gerados que vinculam o motor.
+
+`init` cria a configuração e copia os fontes do motor e extractor distribuídos no pacote para o projeto do consumidor, preservando arquivos existentes. O CLI usa `acbr.config.json`. Todos os caminhos relativos são resolvidos pelo diretório desse arquivo, independentemente do diretório atual do terminal. Campos desconhecidos, revisão inválida ou outra origem SVN são rejeitados.
+
+```sh
+acbr-node init
+acbr-node source update
+acbr-node generate
+acbr-node build
+acbr-node check
+acbr-node doctor
+```
+
+`source update` é a única operação que busca alterações do SVN. Primeiro resolve `HEAD` para um número, exporta `Fontes`, schemas NF-e e licença para uma área temporária e registra a revisão e SHA256 de cada arquivo em `acbr.lock.json`. Se já houver fontes, precisa de um lock válido e recusa arquivos alterados, adicionados ou removidos. A geração, compilação e execução não atualizam fontes automaticamente.
+
+`source update` sem `--revision` consulta a revisão mais recente (`HEAD`), mesmo quando a configuração registra uma revisão anterior. `source update --revision 48590` seleciona explicitamente uma revisão. Após download e lock bem-sucedidos, o CLI persiste a revisão numérica resolvida na configuração, preservando os caminhos e demais campos. Falhas restauram fontes e lock; nenhuma atualização acontece na execução normal. Um export previamente obtido e conferido pelo operador pode ser registrado com `source lock --revision 48590`; esse comando confia na origem declarada pelo operador e calcula os hashes locais, sem comparar o conteúdo com o SVN remoto.
+
+`generate` recria os tipos em `generated/acbr/models.ts`, o mapper Pascal em `native/generated/AcbrModels.pas` e os manifestos/relatórios em `.acbr/generated`. Revise o relatório após cada atualização para detectar campos novos, removidos, enums e partes que o gerador não suporta.
+
+`build` confere fontes/contrato antes de invocar o Free Pascal. Usa os defines `NOGUI` e `NOREPORT`, unidades Lazarus sem interface gráfica, ACBr original e mapper gerado. Linux x64 e Windows x64 são os alvos iniciais. A compilação precisa ocorrer no sistema do alvo; não há cross-compilation implícita.
+
+No Linux, instale Free Pascal 3.2.2, Lazarus 3.0, SVN, OpenSSL 3, libxml2, tar/gzip e certificados CA do sistema. `native.lazarusRoot` ou `LAZARUS_ROOT` podem indicar outra instalação. O staging copia OpenSSL/libxml2 e suas dependências transitivas como bibliotecas dinâmicas com suas licenças e origem/versionamento dos pacotes fonte. Inclui o provider legacy e configuração de providers OpenSSL. glibc e o loader permanecem requisitos do sistema. O Linux usa glibc: o runtime não equivale a um binário portátil para qualquer distribuição ou Alpine.
+
+No Windows, configure `native.lazarusRoot`, `native.fpc`, `native.providerFiles` (incluindo `legacy.dll`) e `native.libraryFiles` para as DLLs x64 de TLS/XML. Cada DLL exige um arquivo de licença adjacente `<DLL>.LICENSE`; `<DLL>.SOURCE.json` registra opcionalmente origem e versão do código correspondente e é incluído na proveniência do runtime. As dependências também podem ser compiladas no WSL com MinGW, conforme [Dependências nativas](DEPENDENCIAS-NATIVAS.md). O motor Pascal é compilado no Windows pelo CLI; a compilação não substitui a homologação fiscal. A [receita de CI](CI.md) documenta instalação oficial gratuita, `FPC_ROOT`/`LAZARUS_ROOT` e criação de um `fpc.cfg` exclusivo com `PPC_CONFIG_PATH`, sem alterar a instalação do compilador.
+
+No Windows, execute comandos `npm` em uma pasta local, por exemplo `C:\Projetos\MinhaAplicacao`. O launcher `npm.cmd` usa `cmd.exe`, que não mantém um caminho UNC como diretório atual. Para trabalhar com um checkout WSL acessado por `\\wsl.localhost\...`, execute a CLI por `node caminho\dist\cli.js` e, quando necessário, invoque `npm-cli.js` diretamente por Node, indicando o caminho da instalação. Na compilação Pascal, fontes em uma pasta Windows local evitam o custo de leitura por UNC; `source.directory` pode apontar para essa cópia e o lock confere os mesmos hashes.
+
+O runtime fica em `.acbr/runtime/<platform>-<arch>`, contendo executável, bibliotecas dinâmicas, schemas, serviços NF-e, licenças, fontes correspondentes e `manifest.json`. O manifesto registra revisão ACBr, contrato, plataforma e SHA256 de cada arquivo. `check` verifica todos esses vínculos e arquivos e depois inicia o motor real em quatro probes locais: gera uma NF-e55 sintética para conferir mapper/chave/UTF-8, valida uma fixture XML assinada com certificado público sintético e recusa XML malformado e DTD/entidade externa. O smoke não recebe PFX, chave privada ou senha e não transmite documentos; `--json` inclui `offlineChecks`. A fixture assinada fica embutida no CLI, pois o schema exige `Signature` e o XML gerado sem A1 ainda não é assinado. O builder confere SHA256 dos três arquivos gerados antes e depois da compilação; uma alteração de mapper/helper invalida o build mesmo quando o hash do contrato permanece igual. O staging inclui notices FPC (GPL do compilador, LGPL e exceção da RTL), Lazarus e das bibliotecas dinâmicas, além da proveniência das cópias usadas. `doctor` informa ferramentas e dependências encontradas; ele não instala ferramentas nem transmite documentos.
+
+Atualizações concorrentes são recusadas com `acbr.lock.json.operation`. Se um processo encerrar abruptamente, confira o PID registrado antes de remover o marcador. Uma alteração de revisão durante a compilação invalida o resultado. O log FPC completo fica em `.acbr/build.log`.
+
+Use `--config caminho` para escolher a configuração e `--json` para obter saída estruturada. Nunca inclua senhas ou certificados nesse arquivo de build: a API recebe essas credenciais separadamente em memória.