Deadlatch

Deadlatch

A trava pré-negociação para o seu agente de trading. Somente consultivo.

Três coisas que você precisa saber antes de qualquer outra:

1. Você precisa de uma barreira independente e entre corretoras que você controla. Se um agente pode colocar ordens na sua conta, a última verificação entre o agente e a corretora não deve ser o próprio agente — e não deve estar presa à interface ou às regras de uma única corretora.
2. O Deadlatch não prevê, não recomenda e não coloca ordens. Ele responde apenas a uma pergunta: esta ordem é permitida agora? Não é um gerador de sinais e não é uma corretora.
3. Toda resposta vem com motivos, evidências e um registro de auditoria local em Linux/macOS. PASS / WARN / BLOCK nunca é um veredito simples — você pode ver qual regra foi acionada, por quê e o que foi avaliado. Gravações de auditoria duráveis (init / append / repair / prune / relatório de sombra) são suportadas apenas em Linux e macOS. No Windows, o pacote ainda é importado, e o mecanismo de regras / Guard / CLI / MCP ainda calculam decisões; esses caminhos de gravação falham de forma fechada com audit_platform_unsupported. A verify / read offline de um snapshot interrompido permanece disponível. O MCP no Windows é um caminho de integração limitado, não uma cadeia de auditoria confiável completa.

Limite honesto (por favor, leia): O Deadlatch é consultivo. Ele não pode forçar um agente que nunca o chama a chamá-lo, e não pode impedir um agente que ignora um BLOCK de enviar a ordem para outro lugar. Se o agente chama a barreira e honra o resultado é uma decisão do integrador. Não confie nesta ferramenta como uma garantia contra perdas — ela é uma barreira, não uma apólice de seguro.

• Licença: MIT — veja LICENSE.
• 中文文档: README.zh-CN.md
• Segurança: SECURITY.md · Contribuição: CONTRIBUTING.md · Aviso legal: DISCLAIMER.md

Comece por aqui

O caminho de instalação atual é o PyPI deadlatch==0.1.2 verificado, publicado em 2026-09-22. O Release estável v0.1.2 do GitHub tem como alvo b072e8a4d4b053e1d5a428dbb9c47e06652fbf4c; seus artefatos wheel/sdist correspondem aos originais do PyPI.

pip install deadlatch==0.1.2

O nome publicado no Registro MCP é io.github.Diabloluo/deadlatch na versão 0.1.2, verificado como ativo/mais recente em 2026-09-22. O server.json local corresponde a essa versão publicada. O comando abaixo inicia o pacote PyPI verificado diretamente.

Início com MCP primeiro:

uvx --from deadlatch==0.1.2 deadlatch-mcp --policy policy.yaml --portfolio portfolio.json

--policy e --portfolio são arquivos locais obrigatórios. --audit-path e --kill-switch-path são opcionais. Use apenas entradas fictícias ou simulações próprias. O Deadlatch é somente consultivo: ele nunca coloca ordens e não pode impedir um agente que nunca o chama. Ordens de opções devem usar o código de contrato completo exclusivo da corretora como symbol. Uma pré-lançamento histórica do GitHub permanece em v0.1.0.dev1; não é o caminho de instalação atual.

Em seguida:

1. Execute um Quick Start com dados fictícios abaixo (Python, CLI ou MCP) em Linux ou macOS. Confirme PASS → BLOCK → auditoria local. O Windows pode importar o pacote e executar o cálculo de regras; não é o Quick Start de gravação de auditoria.
2. Solicite uma avaliação de integração de 20 minutos somente se você já tiver um caminho de intenção de ordem ou execução simulada: abra o formulário de avaliação.

Esse issue do GitHub é público. Não cole contas, posições, ordens, chaves de API, tokens, nomes de clientes ou caminhos privados. Defeitos de segurança devem passar por GitHub Security Advisories, não por um issue público.

---

Quick Start (60 segundos cada)

Todos os três quick starts usam dados fictícios e um caminho de auditoria temporário. Eles são executados a partir dos mesmos scripts-fonte pela suíte de testes, portanto não podem divergir da documentação. O Quick Start completo de gravação de auditoria / MCP requer Linux ou macOS. O Windows pode importar a biblioteca e avaliar regras; não inicializará nem anexará uma coleção de auditoria durável.

1. API Python

pip install dist/deadlatch-*.whl        # or: pip install -e .
python docs/quickstart/python.py

Mostra Guard.from_policy(...) → Order / Portfolio → guard.check(...): uma ordem válida retorna PASS / 0; uma ordem superdimensionada retorna BLOCK / 3 com as regras acionadas; em BLOCK o chamador de exemplo para — nenhuma chamada de corretora é feita.

2. CLI

bash docs/quickstart/cli.sh                  # requires `deadlatch` on PATH

Cria entradas novas em um diretório temporário (timestamps dinâmicos — nunca fica desatualizado), depois executa deadlatch check para PASS (exit 0), BLOCK (exit 3), um erro de entrada (exit 4) e uma verificação de --json, além de shadow report --json sobre a auditoria.

3. MCP (stdio)

python docs/quickstart/mcp_client.py         # requires `deadlatch` installed

Inicia deadlatch-mcp como um subprocesso real via stdio, lista as cinco ferramentas e chama check_order uma vez para PASS e uma vez para BLOCK. Os caminhos policy / portfolio / audit são configuração de inicialização do servidor — um agente não pode trocá-los como argumentos de ferramenta. BLOCK é uma restrição que o chamador deve honrar; tecnicamente, a barreira não pode forçar um agente que contorna completamente a chamá-la.

---

O que é / o que não é

Deadlatch é	Deadlatch não é
Uma barreira de risco local e determinística avaliada antes do envio	Um gerador de sinais, recomendador ou otimizador de portfólio
Uma biblioteca, um CLI e um servidor MCP stdio — sem conectividade com corretoras, sem mutação de políticas	Um adaptador de corretora, um mecanismo de execução ou um feed de mercado
Uma verificação auditável: cada avaliação é gravada em um log JSONL local	Um serviço em nuvem, um banco de dados ou um coletor de telemetria
Somente USD, ordens de uma única perna, um snapshot por verificação (v0.1)	Multi-perna, multi-moeda, ciente de Gregas/IV (veja limitações)

Quem deve usar

• Equipes que já têm um caminho de intenção de ordem ou execução simulada e querem uma barreira pré-negociação independente e determinística com trilha de auditoria local.
• Desenvolvedores que querem um bloco de construção pequeno, com poucas dependências e que falha de forma fechada, para integrar em seu próprio pipeline de execução.
• Qualquer pessoa que queira avaliar ordens contra uma política que ela controla, expressa em YAML simples.

Quem não deve usar: qualquer pessoa que espere garantia de lucro, um mecanismo de backtest, um gerenciador de portfólio ou uma ferramenta que se imponha. Se o agente nunca chama a barreira, ou ignora um BLOCK, nada neste repositório pode impedi-lo.

Limite central de segurança

• Local: tudo roda na sua máquina; nenhuma credencial de conta é armazenada, lida ou transmitida.
• Sem caminho de rede no núcleo: a biblioteca, o CLI e o servidor MCP nunca abrem um socket, nunca registram uma rota HTTP/SSE e nunca buscam cotações ou qualquer outra coisa (a pilha HTTP do SDK MCP é uma dependência transitiva que o código de negócios nunca importa).
• Nunca coloca ordens: o pacote principal (biblioteca, CLI, servidor MCP) não tem conectividade com corretoras e nunca envia ordens. Exemplos experimentais de mapeamento somente leitura existem apenas no workspace de desenvolvimento; não estão incluídos no candidato público nem no wheel, e não são integrações verificadas ao vivo.
• Falha fechada: dados ausentes ou malformados → BLOCK (exit 3); erros de entrada/configuração → exit 4; erros internos → exit 5. Um estado incerto nunca é relatado como PASS.
• Direção derivada do snapshot: o texto do lado da ordem nunca é aceito como prova de fechamento. A intenção de fechamento de ações e opções é reconhecida somente quando um snapshot de portfólio recente contém uma posição correspondente, de lado oposto, com quantidade suficiente. Para opções, symbol deve ser o código de contrato completo exclusivo da corretora; nunca reutilize um ticker subjacente em diferentes vencimentos, strikes ou direitos.
• Somente USD (v0.1): qualquer incompatibilidade de moeda (ordem, portfólio, posições) é um erro de entrada (exit 4); a ferramenta MCP de status de conta falha de forma fechada em incompatibilidade.

Superfície de gravação: a ferramenta nunca modifica policy, portfolio ou o estado do kill-switch, nunca se conecta a uma corretora e nunca coloca uma ordem. Existem dois tipos de gravações intencionais de arquivos locais:

1. Subsistema de auditoria: Guard.check() / check_order anexam um registro v2 sanitizado a um shard diário UTC ao lado do caminho lógico de auditoria (retenção de 30 dias). Anexar é uma gravação de cauda limitada sob um lock compartilhado; não reescreve o histórico. Uma nova coleção precisa de um deadlatch audit init explícito (ou initialize_audit_state) antes de anexar; Guard/MCP nunca fazem migração automática. deadlatch shadow report e deadlatch audit prune excluem arquivos de shard inteiros que ficam fora da janela de 30 dias corridos. deadlatch audit repair --quarantine ainda usa arquivos de lock/tmp e os.replace quando isola uma cauda truncada. Anexar comum não é atômico entre arquivos em caso de crash. Locks POSIX são entre processos. As gravações de auditoria duráveis v0.1.2 são somente Linux/macOS; gravadores no Windows recebem audit_platform_unsupported e não pulam o fsync do diretório para relatar sucesso.
2. Saída explícita de migração: deadlatch migrate --output <file> grava o documento migrado somente quando você passa explicitamente --output.

O contrato público para essas regras, limites Decimal, códigos de saída e requisitos de símbolos de opções está em docs/rules-spec.md.

As 12 regras (v0.1)

#	Regra	O que protege
R1	kill_switch	Interruptor global: off / full (bloquear tudo) / reduce_only (permitir apenas ordens de fechamento inferidas)
R2	input_validity	A ordem passa no schema, na verificação de versão, na consistência de moeda, em valores finitos (violações → exit 4)
R3	max_order_quantity	Limite de quantidade por ordem
R4	max_order_value	Limite de nocional por ordem (opções: preço × multiplicador × quantidade)
R5	max_symbol_exposure	Exposição por subjacente (opções por strike × multiplicador × quantidade)
R6	max_total_exposure	Razão de exposição bruta do portfólio
R7	cash_margin_check	Piso de caixa pós-negociação e margem de opção vendida
R8	max_daily_loss	Razão de perda diária (PnL / patrimônio no início do dia)
R9	max_drawdown	Razão de drawdown a partir do pico
R10	order_time_validity	Idade da ordem / timestamps futuros (não analisável → BLOCK por falha fechada)
R11	data_freshness	Frescor do snapshot do portfólio (snapshot futuro → falha fechada)
R12	missing_data_fail_closed	Dados de portfólio ausentes/nulos/malformados → exit 3 (dados inutilizáveis = risco)

Regras opcionais (R3–R7) são alternadas por suas chaves de configuração em policy.yaml; uma chave opcional ausente deve ser declarada em acknowledged_disabled ou a política é rejeitada (exit 4). Regras obrigatórias (R1, R2, R8–R12) nunca podem ser desabilitadas.

Códigos de saída

Código	Significado
0	PASS — a ordem é permitida como está
2	WARN — prossiga somente se sua política de execução permitir explicitamente avisos
3	BLOCK — a ordem não deve ser enviada (regra de risco ou dados com falha fechada)
4	Erro de entrada / configuração — o chamador usou mal a API, não é um evento de risco
5	Exceção interna / de regra — tratada como BLOCK (falha fechada)

No modo sombra, o veredito interno é registrado (shadow_verdict) enquanto a projeção externa é PASS / 0; acionamentos de kill-switch e exit 4/5 nunca são projetados para fora.

Contratos de dados e migração

Schemas são arquivos versionados JSON Schema 2020-12 enviados dentro do pacote: order, portfolio, policy, result, audit-record, shadow-report, audit-maintenance-result, audit-prune-result, audit-write-state, audit-state-result. A migração offline explícita está disponível para documentos legados:

deadlatch migrate --kind order    --input order_v1.json    [--output out.json]
deadlatch migrate --kind policy   --input policy_v1.json   [--output out.json]
deadlatch migrate --kind portfolio --input portfolio_v1.json [--output out.json]

A migração converte apenas campos adjudicados (por exemplo, kill-switch booleano da política v1 → off/full); nunca adivinha campos de negócio. Entradas de avaliação normais rejeitam versões antigas (exit 4) em vez de migrar silenciosamente.

Log de auditoria

Cada Guard.check() anexa um registro v2 a um shard de dia UTC ao lado do caminho lógico (padrão ~/.deadlatch/audit.jsonl, substituível via --audit-path / DEADLATCH_AUDIT_PATH). Uma nova coleção deve ser inicializada uma vez com deadlatch audit init / initialize_audit_state antes do anexo; estado ausente recusa a gravação e não verifica o diretório para reconstruí-lo. Arquivos únicos anteriores à v0.1.2 permanecem legíveis como v1 legado. Os registros são validados por esquema e sanitizados (sem credenciais, cookies ou caminhos absolutos em texto simples). A retenção é de 30 dias corridos de shards; o anexo não reescreve mais o histórico. A data do shard UTC é decidida após o bloqueio da coleção ser mantido (relógio padrão ou now explícito). Um marca-d'água durável de data de gravação (audit.jsonl.state.json) recusa qualquer dia UTC anterior após um dia posterior ter sido reservado, incluindo lacunas de 30/365 dias; os bytes originais do log e do estado permanecem inalterados. O marca-d'água é controle sequencial, não uma assinatura. evaluated_at não é reescrito. Use deadlatch shadow report ou deadlatch audit prune para excluir shards expirados. Arquivos legados não são excluídos automaticamente. Se a gravação de auditoria falhar, o resultado retornado é degradado somente gravidade: PASS/0 → WARN/2; BLOCK/3/4/5 mantém sua decisão e apenas anexa um aviso audit_write_failed — o disco e o Resultado retornado nunca se contradizem. Consulte docs/audit-write-state.md.

Os registros v0.1.2 carregam uma cadeia de hash SHA-256 local (prev_hash / record_hash). A cadeia é evidente contra adulteração, não uma assinatura digital e não é à prova de adulteração. Um atacante que possa reescrever todo o diretório e recalcular hashes está fora do escopo. Sem uma âncora imutável externa, excluir o último registro atual ou todo o conjunto visível não é detectável de forma confiável apenas pela cadeia.

deadlatch audit verify verifica a coleção visível (legado mais shards UTC na janela de 30 dias corridos e quaisquer shards futuros que a poda mantenha) sem alterar o conteúdo ou gravar quarentena. Shards expirados podem permanecer não podados e não fazem parte dessa verificação de cadeia. Para uma coleção existente, pode criar um sidecar .lock para compartilhar o mesmo bloqueio que anexo/reparação/poda. Linhas legadas v1 danificadas ainda podem ser isoladas com deadlatch audit repair --quarantine. A reparação v2 apenas isola uma última linha truncada do último shard; incompatibilidades de hash, IDs duplicados, rebaixamentos de versão e danos no meio da cadeia recusam a religação automática (saída 3, sem gravações). O relatório de sombra e o MCP recent_decisions leem o mesmo instantâneo sob o mesmo bloqueio e verificam hashes, links de cadeia, IDs duplicados e localização da versão antes de retornar registros; uma cadeia adulterada ou rebaixada não é apresentada como histórico confiável. A compatibilidade v1 é limitada ao arquivo de linha de base legado e apenas antes de qualquer registro v2 — uma linha v1 em um shard de dia UTC é recusada. Consulte docs/postmortem-option-direction.md para uma explicação fictícia da correção da direção da opção G1.

Servidor MCP

deadlatch-mcp é um servidor MCP somente stdio (sem listener TCP, sem rotas HTTP/SSE). As cinco ferramentas são somente leitura: nenhuma delas pode modificar policy, portfolio ou o estado do kill-switch (esses caminhos são configuração de inicialização, não argumentos de ferramenta). Mudanças de política são validadas e carregadas automaticamente na próxima chamada de ferramenta. Um arquivo kill-switch independente opcional é lido em cada chamada e só pode tornar a política mais restritiva. Observe que o servidor ainda anexa cada avaliação check_order ao log de auditoria local — isso é por design, não uma capacidade de ferramenta. Cinco ferramentas:

Ferramenta	Propósito
check_order	Avalia uma ordem; retorna o result completo (decisão, código de saída, violações, evidência)
get_account_status	Atualidade do instantâneo, patrimônio líquido, caixa, PnL, rebaixamento, utilização de exposição
get_policy	Projeção somente leitura da política efetiva
kill_switch_status	Modo atual do kill-switch (somente leitura; nenhuma ferramenta pode alterá-lo)
recent_decisions	Registros de auditoria recentes (mais antigos primeiro, since/limit opcionais)

Inicie com:

deadlatch-mcp --policy policy.yaml --portfolio portfolio.json \
  [--audit-path audit.jsonl] [--kill-switch-path kill-switch]

Os argumentos de caminho são apenas configuração de inicialização; seus conteúdos de arquivo permanecem estado local ativo. Um arquivo kill-switch configurado deve conter exatamente off, reduce_only ou full. Ele não pode enfraquecer um modo mais restritivo já presente na política. Uma política/switch ativo ausente, malformado ou concorrentemente instável falha fechado: erros de ferramenta são isError=true + fail_closed, e erros de configuração carregam input_error=true + exit_code=4.

Demonstração

Um agente chama check_order com uma ordem superdimensionada; o guarda retorna BLOCK / 3 com as regras atingidas; o agente para em vez de chamar qualquer ferramenta de corretora. Gerado a partir de uma execução real local de MCP stdio com dados fictícios (tools/make_demo_gif.py):

Limitações conhecidas (v0.1)

• O risco de alta de call curto descoberto é ilimitado. A v0.1 usa uma aproximação de exposição baseada em strike e não modela essa cauda ilimitada; não trate isso como um limite conservador para calls curtos.
• A saída de caixa de venda a descoberto é modelada como 0 (simplificação documentada).
• Sem Gregas, IV, estratégias de múltiplas pernas ou carteiras em múltiplas moedas.
• O bloqueio entre processos de auditoria depende de fcntl POSIX; em plataformas não POSIX, o bloqueio degrada para um bloqueio local ao processo (sem garantia entre processos).
• Gravações de auditoria duráveis na v0.1.2 são suportadas apenas em Linux e macOS. Windows e outras plataformas recusam init / append / repair / prune / relatório de sombra com audit_platform_unsupported antes de criar bloqueios ou gravar estado. Falhas de fsync de arquivo e diretório em plataformas suportadas permanecem falha fechada; não são tratadas como "capacidade ausente". Verificação/leitura offline de um instantâneo parado permanece disponível. Escritores concorrentes no Windows estão fora do escopo.
• O guarda não pode impedir desvio completo: um agente que nunca o chama, ou que ignora um BLOCK e chama a corretora diretamente, não pode ser impedido por esta ferramenta.
• Exemplos no repositório usam apenas tickers e dados fictícios.

Governança

• SECURITY.md — versões suportadas, escopo de vulnerabilidades, relatórios.
• docs/rules-spec.md — contrato público de 12 regras.
• CONTRIBUTING.md — ambiente, comandos de teste/esquema/varredura/cobertura, disciplina de regras.
• DISCLAIMER.md — aviso legal/risco completo (resumo abaixo).
• README.zh-CN.md — 中文文档.

Aviso (resumo): não é aconselhamento de investimento; sem garantia contra perdas; verifique entradas e regras você mesmo; o guarda nunca coloca ordens; todos os exemplos são fictícios; teste antes de negociar capital real; sem SLA. Consulte DISCLAIMER.md na íntegra.