Deadlatch

Deadlatch

El candado previo a la negociación para tu agente de trading. Solo consultivo.

Tres cosas que necesitas saber antes que nada:

1. Necesitas una puerta independiente y entre corredores que tú controles. Si un agente puede colocar órdenes en tu cuenta, la última verificación entre el agente y el corredor no debería ser el propio agente — y no debería estar bloqueada a la interfaz o reglas de un solo corredor.
2. Deadlatch no predice, no recomienda y no coloca órdenes. Responde una sola pregunta: ¿está permitida esta orden ahora mismo? No es un generador de señales ni un corredor.
3. Cada respuesta viene con razones, evidencia y un registro de auditoría local en Linux/macOS. PASS / WARN / BLOCK nunca es un veredicto desnudo — puedes ver qué regla se activó, por qué y qué se evaluó. Las escrituras de auditoría duraderas (init / append / repair / prune / informe de sombra) son compatibles solo en Linux y macOS. En Windows el paquete aún se importa, y el motor de reglas / Guard / CLI / MCP aún calculan decisiones; esas rutas de escritura fallan de forma cerrada con audit_platform_unsupported. La verify / read sin conexión de una instantánea detenida sigue disponible. Windows MCP es una ruta de integración limitada, no una cadena de auditoría confiable completa.

Límite honesto (por favor lee): Deadlatch es consultivo. No puede obligar a un agente que nunca lo llama a llamarlo, y no puede detener a un agente que ignora un BLOCK de enviar la orden a otro lugar. Si el agente llama al guard y respeta el resultado es decisión del integrador. No confíes en esta herramienta como garantía contra pérdidas — es una puerta, no una póliza de seguro.

• Licencia: MIT — ver LICENSE.
• 中文文档: README.zh-CN.md
• Seguridad: SECURITY.md · Contribuciones: CONTRIBUTING.md · Descargo de responsabilidad: DISCLAIMER.md

Comienza aquí

La ruta de instalación actual es el PyPI deadlatch==0.1.2 verificado, publicado el 2026-09-22. El Release estable de GitHub v0.1.2 apunta a b072e8a4d4b053e1d5a428dbb9c47e06652fbf4c; sus activos wheel/sdist coinciden con los originales de PyPI.

pip install deadlatch==0.1.2

El nombre publicado del Registro MCP es io.github.Diabloluo/deadlatch en la versión 0.1.2, verificado como activo/último el 2026-09-22. El server.json local coincide con esa versión publicada. El comando a continuación inicia directamente el paquete verificado de PyPI.

Inicio primero con MCP:

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

--policy y --portfolio son archivos locales requeridos. --audit-path y --kill-switch-path son opcionales. Usa solo entradas ficticias o simuladas propias. Deadlatch es solo consultivo: nunca coloca órdenes y no puede detener a un agente que nunca lo llama. Las órdenes de opciones deben usar el código de contrato completo único del corredor como symbol. Una pre-release histórica de GitHub permanece en v0.1.0.dev1; no es la ruta de instalación actual.

Luego:

1. Ejecuta un Quick Start con datos ficticios a continuación (Python, CLI o MCP) en Linux o macOS. Confirma PASS → BLOCK → auditoría local. Windows puede importar el paquete y ejecutar el cálculo de reglas; no es el Quick Start de escritura de auditoría.
2. Solicita una evaluación de integración de 20 minutos solo si ya tienes una ruta de intención de orden o ejecución simulada: abre el formulario de evaluación.

Ese issue de GitHub es público. No pegues cuentas, posiciones, órdenes, claves API, tokens, nombres de clientes o rutas privadas. Los defectos de seguridad deben pasar por GitHub Security Advisories, no por un issue público.

---

Quick Start (60 segundos cada uno)

Los tres quick starts usan datos ficticios y una ruta de auditoría temporal. Son ejecutados desde los mismos scripts fuente por el conjunto de pruebas, por lo que no pueden desviarse de la documentación. El Quick Start completo de escritura de auditoría / MCP requiere Linux o macOS. Windows puede importar la biblioteca y evaluar reglas; no inicializará ni añadirá una colección de auditoría duradera.

1. API de Python

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

Muestra Guard.from_policy(...) → Order / Portfolio → guard.check(...): una orden válida devuelve PASS / 0; una orden sobredimensionada devuelve BLOCK / 3 con las reglas activadas; en BLOCK el llamador de ejemplo se detiene — nunca se realiza una llamada al corredor.

2. CLI

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

Crea entradas nuevas en un directorio temporal (marcas de tiempo dinámicas — nunca se vuelve obsoleto), luego ejecuta deadlatch check para PASS (exit 0), BLOCK (exit 3), un error de entrada (exit 4) y una verificación de --json, además de shadow report --json sobre la auditoría.

3. MCP (stdio)

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

Inicia deadlatch-mcp como un subproceso real sobre stdio, lista las cinco herramientas y llama a check_order una vez para PASS y una vez para BLOCK. Las rutas policy / portfolio / audit son configuración de inicio del servidor — un agente no puede cambiarlas como argumentos de herramienta. BLOCK es una restricción que el llamador debe respetar; técnicamente el guard no puede obligar a un agente que lo evita por completo a llamarlo.

---

Qué es / qué no es

Deadlatch es	Deadlatch no es
Una puerta de riesgo local y determinista evaluada antes de que envíes	Un generador de señales, recomendador u optimizador de cartera
Una biblioteca, una CLI y un servidor MCP stdio — sin conectividad con corredores, sin mutación de políticas	Un adaptador de corredor, un motor de ejecución o un feed de mercado
Una verificación auditable: cada evaluación se escribe en un registro JSONL local	Un servicio en la nube, una base de datos o un sumidero de telemetría
Solo USD, órdenes de una sola pata, una instantánea por verificación (v0.1)	Multi-pata, multi-moneda, consciente de Griegas/IV (ver limitaciones)

Quién debería usarlo

• Equipos que ya tienen una ruta de intención de orden o ejecución simulada y quieren una puerta previa a la negociación independiente y determinista con un rastro de auditoría local.
• Desarrolladores que quieren un bloque de construcción pequeño, con pocas dependencias y de fallo cerrado que puedan integrar en su propio pipeline de ejecución.
• Cualquiera que quiera evaluar órdenes contra una política que ellos controlan, expresada como YAML simple.

Quién no debería usarlo: cualquiera que espere una garantía de ganancias, un motor de backtest, un gestor de cartera o una herramienta que se haga cumplir a sí misma. Si el agente nunca llama al guard, o ignora un BLOCK, nada en este repositorio puede detenerlo.

Límite de seguridad central

• Local: todo se ejecuta en tu máquina; ninguna credencial de cuenta se almacena, lee o transmite jamás.
• Sin ruta de red central: la biblioteca, CLI y servidor MCP nunca abren un socket, nunca registran una ruta HTTP/SSE y nunca llaman para obtener cotizaciones ni nada más (la pila HTTP del SDK de MCP es una dependencia transitiva que el código de negocio nunca importa).
• Nunca coloca órdenes: el paquete central (biblioteca, CLI, servidor MCP) no tiene conectividad con corredores y nunca envía órdenes. Los ejemplos experimentales de mapeo de solo lectura existen solo en el espacio de trabajo de desarrollo; no están incluidos en el candidato público ni en el wheel, y no son integraciones verificadas en vivo.
• Fallo cerrado: datos faltantes o malformados → BLOCK (exit 3); errores de entrada/configuración → exit 4; errores internos → exit 5. Un estado incierto nunca se reporta como PASS.
• La dirección se deriva de la instantánea: el texto del lado de la orden nunca se acepta como prueba de un cierre. La intención de cierre de acciones y opciones se reconoce solo cuando una instantánea de cartera fresca contiene una posición coincidente del lado opuesto con cantidad suficiente. Para opciones, symbol debe ser el código de contrato completo único del corredor; nunca reutilices un ticker subyacente entre diferentes vencimientos, strikes o derechos.
• Solo USD (v0.1): cualquier discrepancia de moneda (orden, cartera, posiciones) es un error de entrada (exit 4); la herramienta de estado de cuenta de MCP falla de forma cerrada ante discrepancias.

Superficie de escritura: la herramienta nunca modifica policy, portfolio ni el estado del interruptor de apagado, nunca se conecta a un corredor y nunca coloca una orden. Existen dos tipos de escrituras de archivos locales intencionales:

1. Subsistema de auditoría: Guard.check() / check_order añaden un registro v2 saneado a un fragmento de día UTC junto a la ruta de auditoría lógica (retención de 30 días). La adición es una escritura de cola limitada bajo un bloqueo compartido; no reescribe el historial. Una nueva colección necesita una deadlatch audit init explícita (o initialize_audit_state) antes de añadir; Guard/MCP nunca auto-migran. deadlatch shadow report y deadlatch audit prune eliminan archivos de fragmentos completos que quedan fuera de la ventana de 30 días calendario. deadlatch audit repair --quarantine aún usa archivos de bloqueo/temporales y os.replace cuando aísla una cola truncada. La adición ordinaria no es atómica ante fallos entre archivos. Los bloqueos POSIX son entre procesos. Las escrituras de auditoría duraderas v0.1.2 son solo Linux/macOS; los escritores de Windows reciben audit_platform_unsupported y no omiten el fsync del directorio para reportar éxito.
2. Salida de migración explícita: deadlatch migrate --output <file> escribe el documento migrado solo cuando pasas explícitamente --output.

El contrato público para estas reglas, umbrales Decimal, códigos de salida y requisitos de símbolos de opciones está en docs/rules-spec.md.

Las 12 reglas (v0.1)

#	Regla	Qué protege
R1	kill_switch	Interruptor global: off / full (bloquear todo) / reduce_only (permitir solo órdenes de cierre inferidas)
R2	input_validity	La orden pasa esquema, compuerta de versión, consistencia de moneda, montos finitos (violaciones → exit 4)
R3	max_order_quantity	Límite de cantidad de orden única
R4	max_order_value	Límite de nocional de orden única (opciones: precio × multiplicador × cantidad)
R5	max_symbol_exposure	Exposición por subyacente (opciones por strike × multiplicador × cantidad)
R6	max_total_exposure	Ratio de exposición bruta de cartera
R7	cash_margin_check	Piso de efectivo post-negociación y margen de opciones cortas
R8	max_daily_loss	Ratio de pérdida diaria (PnL / capital al inicio del día)
R9	max_drawdown	Ratio de reducción desde el pico
R10	order_time_validity	Edad de la orden / marcas de tiempo futuras (no analizable → BLOCK de fallo cerrado)
R11	data_freshness	Frescura de la instantánea de cartera (instantánea futura → fallo cerrado)
R12	missing_data_fail_closed	Datos de cartera faltantes/nulos/malformados → exit 3 (datos inutilizables = riesgo)

Las reglas opcionales (R3–R7) se activan mediante sus claves de configuración en policy.yaml; una clave opcional faltante debe declararse en acknowledged_disabled o la política se rechaza (exit 4). Las reglas obligatorias (R1, R2, R8–R12) nunca se pueden desactivar.

Códigos de salida

Código	Significado
0	PASS — la orden está permitida tal como está
2	WARN — procede solo si tu política de ejecución permite explícitamente advertencias
3	BLOCK — la orden no debe enviarse (regla de riesgo o datos de fallo cerrado)
4	Error de entrada / configuración — el llamador usó mal la API, no es un evento de riesgo
5	Excepción interna / de regla — tratada como BLOCK (fallo cerrado)

En modo sombra, el veredicto interno se registra (shadow_verdict) mientras la proyección externa es PASS / 0; los impactos del interruptor de apagado y exit 4/5 nunca se proyectan fuera.

Contratos de datos y migración

Los esquemas son archivos JSON Schema 2020-12 versionados enviados dentro del paquete: order, portfolio, policy, result, audit-record, shadow-report, audit-maintenance-result, audit-prune-result, audit-write-state, audit-state-result. La migración explícita sin conexión está disponible para documentos heredados:

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]

La migración convierte solo campos adjudicados (por ejemplo, interruptor de apagado booleano de política v1 → off/full); nunca adivina campos de negocio. Las entradas de evaluación normales rechazan versiones antiguas (exit 4) en lugar de migrar silenciosamente.

Registro de auditoría

Cada Guard.check() añade un registro v2 a un shard de día UTC junto a la ruta lógica (por defecto ~/.deadlatch/audit.jsonl, sobreescribible mediante --audit-path / DEADLATCH_AUDIT_PATH). Una nueva colección debe inicializarse una vez con deadlatch audit init / initialize_audit_state antes de añadir; si falta el estado, se rechaza la escritura y no se escanea el directorio para reconstruirlo. Los archivos únicos anteriores a v0.1.2 siguen siendo legibles como v1 heredado. Los registros se validan contra el esquema y se sanean (sin credenciales, cookies ni rutas absolutas en texto plano). La retención es de 30 días naturales de shards; añadir ya no reescribe el historial. La fecha del shard UTC se decide después de mantener el bloqueo de la colección (reloj por defecto o now explícito). Una marca de agua de fecha de escritura duradera (audit.jsonl.state.json) rechaza cualquier día UTC anterior después de que un día posterior haya sido reservado, incluidos huecos de 30/365 días; los bytes originales del registro y del estado permanecen sin cambios. La marca de agua es control secuencial, no una firma. evaluated_at no se reescribe. Use deadlatch shadow report o deadlatch audit prune para eliminar shards caducados. Los archivos heredados no se eliminan automáticamente. Si la escritura de auditoría falla, el resultado devuelto se degrada solo gravedad: PASS/0 → WARN/2; BLOCK/3/4/5 mantiene su decisión y solo adjunta una advertencia audit_write_failed — el disco y el Result devuelto nunca se contradicen. Consulte docs/audit-write-state.md.

Los registros v0.1.2 llevan una cadena de hash SHA-256 local (prev_hash / record_hash). La cadena es evidente de manipulación, no una firma digital y no es a prueba de manipulación. Un atacante que pueda reescribir todo el directorio y recalcular hashes queda fuera de alcance. Sin un ancla inmutable externa, eliminar el último registro actual o todo el conjunto visible no se puede detectar de forma fiable solo con la cadena.

deadlatch audit verify escanea la colección visible (heredada más shards UTC en la ventana de 30 días naturales y cualquier shard futuro que la poda conserve) sin cambiar contenidos ni escribir cuarentena. Los shards caducados pueden permanecer sin podar y no forman parte de esa verificación de cadena. Para una colección existente puede crear un sidecar .lock para poder compartir el mismo bloqueo que añadir/reparar/podar. Las líneas dañadas v1 heredadas aún pueden aislarse con deadlatch audit repair --quarantine. La reparación v2 solo aísla una línea truncada al final del último shard; los desajustes de hash, IDs duplicados, degradaciones de versión y daños en medio de la cadena rechazan el reenlace automático (salida 3, sin escrituras). El informe de sombra y el MCP recent_decisions leen la misma instantánea bajo el mismo bloqueo y verifican hashes, enlaces de cadena, IDs duplicados y ubicación de versión antes de devolver registros; una cadena manipulada o degradada no se presenta como historial de confianza. La compatibilidad v1 se limita al archivo base heredado y solo antes de cualquier registro v2 — una línea v1 en un shard de día UTC se rechaza. Consulte docs/postmortem-option-direction.md para una explicación ficticia de la corrección de dirección de opción G1.

Servidor MCP

deadlatch-mcp es un servidor MCP solo stdio (sin listener TCP, sin rutas HTTP/SSE). Las cinco herramientas son de solo lectura: ninguna puede modificar policy, portfolio ni el estado de kill-switch (esas rutas son configuración de inicio, no argumentos de herramienta). Los cambios de política se validan y cargan automáticamente en la siguiente llamada de herramienta. Un archivo kill-switch independiente opcional se lee en cada llamada y solo puede hacer la política más restrictiva. Tenga en cuenta que el servidor aún añade cada evaluación de check_order al registro de auditoría local — eso es por diseño, no una capacidad de herramienta. Cinco herramientas:

Herramienta	Propósito
check_order	Evaluar una orden; devuelve el result completo (decisión, código de salida, violaciones, evidencia)
get_account_status	Frescura de instantánea, patrimonio, efectivo, PnL, drawdown, utilización de exposición
get_policy	Proyección de solo lectura de la política efectiva
kill_switch_status	Modo kill-switch actual (solo lectura; ninguna herramienta puede cambiarlo)
recent_decisions	Registros de auditoría recientes (más antiguos primero, since/limit opcionales)

Inícielo con:

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

Los argumentos de ruta son solo configuración de inicio; sus contenidos de archivo permanecen como estado local en vivo. Un archivo kill-switch configurado debe contener exactamente off, reduce_only o full. No puede debilitar un modo más estricto ya presente en la política. Una política/switch en vivo faltante, malformada o concurrentemente inestable falla de forma cerrada: los errores de herramienta son isError=true + fail_closed, y los errores de configuración llevan input_error=true + exit_code=4.

Demo

Un agente llama a check_order con una orden sobredimensionada; el guardián devuelve BLOCK / 3 con las reglas activadas; el agente se detiene en lugar de llamar a cualquier herramienta de bróker. Generado a partir de una ejecución real local de MCP stdio con datos ficticios (tools/make_demo_gif.py):

Limitaciones conocidas (v0.1)

• El riesgo de upside de calls cortas desnudas es ilimitado. v0.1 usa una aproximación de exposición basada en strike y no modela esa cola ilimitada; no lo trate como un límite conservador para calls cortas.
• La salida de efectivo por venta en corto se modela como 0 (simplificación documentada).
• Sin griegas, IV, estrategias multi-pata ni libros multi-divisa.
• El bloqueo entre procesos de auditoría depende de fcntl POSIX; en plataformas no POSIX el bloqueo se degrada a un bloqueo local al proceso (sin garantía entre procesos).
• Las escrituras de auditoría duraderas en v0.1.2 solo se admiten en Linux y macOS. Windows y otras plataformas rechazan init / append / repair / prune / informe de sombra con audit_platform_unsupported antes de crear bloqueos o escribir estado. Los fallos de fsync de archivos y directorios en plataformas compatibles permanecen de cierre seguro; no se tratan como "capacidad faltante". La verificación/lectura sin conexión de una instantánea detenida sigue disponible. Los escritores concurrentes de Windows quedan fuera de alcance.
• El guardián no puede prevenir la omisión completa: un agente que nunca lo llama, o que ignora un BLOCK y llama al bróker directamente, no puede ser detenido por esta herramienta.
• Los ejemplos en el repositorio usan solo tickers y datos ficticios.

Gobernanza

• SECURITY.md — versiones compatibles, alcance de vulnerabilidades, reporte.
• docs/rules-spec.md — contrato público de 12 reglas.
• CONTRIBUTING.md — entorno, comandos de test/esquema/escaneo/cobertura, disciplina de reglas.
• DISCLAIMER.md — descargo legal/riesgo completo (resumen abajo).
• README.zh-CN.md — 中文文档.

Descargo (resumen): no es asesoramiento de inversión; sin garantía contra pérdidas; verifique entradas y reglas usted mismo; el guardián nunca coloca órdenes; todos los ejemplos son ficticios; pruebe antes de operar con capital real; sin SLA. Consulte DISCLAIMER.md completo.