deadlatch

# Deadlatch

**The pre-trade latch for your trading agent.** Advisory-only.

Three things you need to know before anything else:

1. **You need an independent, cross-broker gate that you control.** If an agent can place orders on your account, the last check between the agent and the broker should not be the agent itself — and it should not be locked to one broker's UI or rules.
2. **Deadlatch does not predict, does not recommend, and does not place orders.** It answers one question only: *is this order allowed right now?* It is not a signal generator and it is not a broker.
3. **Every answer comes with reasons, evidence, and a local audit record.** PASS / WARN / BLOCK is never a bare verdict — you can see which rule hit, why, and what was evaluated, and every check is appended to a local JSONL audit log.

**Honest boundary (please read):** Deadlatch is advisory. It cannot force an agent that never calls it to call it, and it cannot stop an agent that ignores a BLOCK from submitting the order somewhere else. Whether the agent calls the guard and honors the result is the integrator's decision. Do not rely on this tool as a guarantee against loss — it is a gate, not an insurance policy.

- **License:** MIT — see [LICENSE](LICENSE).
- **中文文档:** [README.zh-CN.md](README.zh-CN.md)
- **Security:** [SECURITY.md](SECURITY.md) · **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md) · **Disclaimer:** [DISCLAIMER.md](DISCLAIMER.md)

## Start here

<!-- mcp-name: io.github.Diabloluo/deadlatch -->

`0.1.0` is the first stable version line. Install the verified package from [PyPI](https://pypi.org/project/deadlatch/0.1.0/):

```bash
pip install deadlatch==0.1.0
```

The MCP Registry name is `io.github.Diabloluo/deadlatch`.

**MCP-first start:**

```bash
uvx --from deadlatch==0.1.0 deadlatch-mcp --policy policy.yaml --portfolio portfolio.json
```

`--policy` and `--portfolio` are required local files. `--audit-path` and `--kill-switch-path` are optional. Use fictional or your own simulated inputs only. Deadlatch is advisory-only: it never places orders and cannot stop an agent that never calls it. Option orders must use the broker's unique full contract code as `symbol`. A historical GitHub pre-release remains at [v0.1.0.dev1](https://github.com/Diabloluo/deadlatch/releases/tag/v0.1.0.dev1); it is not the current install path.

Then:

1. **Run a fictional-data Quick Start** below (Python, CLI, or MCP). Confirm `PASS` → `BLOCK` → local audit.
2. **Request a 20-minute integration assessment** only if you already have an order-intent or simulated execution path: [open the assessment form](https://github.com/Diabloluo/deadlatch/issues/new?template=integration-assessment.yml).

That GitHub issue is **public**. Do not paste accounts, positions, orders, API keys, tokens, customer names, or private paths. Security defects must go through [GitHub Security Advisories](https://github.com/Diabloluo/deadlatch/security/advisories), not a public issue.

---

## Quick Start (60 seconds each)

All three quick starts use fictional data and a temporary audit path. They are executed from the same source scripts by the test suite, so they cannot drift from the documentation.

### 1. Python API

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

Shows `Guard.from_policy(...)` → `Order` / `Portfolio` → `guard.check(...)`:
a valid order returns `PASS / 0`; an oversized order returns `BLOCK / 3` with the
hit rules; on `BLOCK` the example caller stops — no broker call is ever made.

### 2. CLI

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

Creates fresh inputs in a temp directory (dynamic timestamps — never goes stale),
then runs `deadlatch check` for PASS (`exit 0`), BLOCK (`exit 3`), an input
error (`exit 4`), and a `--json` check, plus `shadow report --json` over the audit.

### 3. MCP (stdio)

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

Starts `deadlatch-mcp` as a real subprocess over stdio, lists the five tools,
and calls `check_order` once for PASS and once for BLOCK. `policy` / `portfolio` /
`audit` paths are **server startup configuration** — an agent cannot swap them as
tool arguments. BLOCK is a constraint the caller must honor; technically the guard
cannot force a fully bypassing agent to call it.

---

## What it is / is not

| Deadlatch **is** | Deadlatch **is not** |
|---|---|
| A local, deterministic risk gate evaluated before you submit | A signal generator, recommender, or portfolio optimizer |
| A library, a CLI, and a stdio MCP server — no broker connectivity, no policy mutation | A broker adapter, an execution engine, or a market feed |
| An auditable check: every evaluation is written to a local JSONL log | A cloud service, a database, or a telemetry sink |
| USD-only, single-leg orders, one snapshot per check (v0.1) | Multi-leg, multi-currency, Greeks/IV-aware (see limitations) |

## Who should use it

- Teams that already have an order-intent or simulated execution path and
  want an independent, deterministic pre-trade gate with a local audit trail.
- Developers who want a small, dependency-light, fail-closed building block they
  can integrate into their own execution pipeline.
- Anyone who wants to evaluate orders against a *policy they control*, expressed
  as plain YAML.

**Who should not use it:** anyone expecting a profit guarantee, a backtest engine,
a portfolio manager, or a tool that enforces itself. If the agent never calls the
guard, or ignores a BLOCK, nothing in this repository can stop it.

## Core security boundary

- **Local:** everything runs on your machine; no account credentials are ever
  stored, read, or transmitted.
- **No network core path:** the library, CLI, and MCP server never open a socket,
  never register an HTTP/SSE route, and never call out for quotes or anything else
  (the MCP SDK's HTTP stack is a transitive dependency that business code never imports).
- **Never places orders:** the core package (library, CLI, MCP server) has
  no broker connectivity and never submits orders. Experimental read-only
  mapping examples exist only in the development workspace; they are not
  included in the public candidate or the wheel, and they are not
  live-verified integrations.
- **Fail-closed:** missing or malformed data → BLOCK (`exit 3`); input/config errors →
  `exit 4`; internal errors → `exit 5`. An uncertain state is never reported as PASS.
- **Direction is snapshot-derived:** order-side text is never accepted as proof of a
  close. Stock and option closing intent is recognized only when a fresh portfolio
  snapshot contains a matching, opposite-side position with sufficient quantity.
  For options, `symbol` must be the broker's unique full contract code; never reuse
  an underlying ticker across different expiries, strikes, or rights.
- **USD-only (v0.1):** any currency mismatch (order, portfolio, positions) is an
  input error (`exit 4`); the MCP account-status tool fail-closes on mismatch.

**Write surface:** the tool never modifies `policy`, `portfolio`, or
kill-switch state, never connects to a broker, and never places an order.
Two kinds of intentional local file writes exist:

1. **Audit subsystem:** `Guard.check()` / `check_order` append one sanitized
   record to the local audit JSONL (30-day retention); the shadow-report
   entry point (`deadlatch shadow report`) triggers the same retention
   pruning, which atomically rewrites the audit file when expired records
   exist; the audit implementation uses lock/tmp files and `os.replace` to
   make each transaction atomic.
2. **Explicit migration output:** `deadlatch migrate --output <file>`
   writes the migrated document only when you explicitly pass `--output`.

## The 12 rules (v0.1)

| # | Rule | What it guards |
|---|---|---|
| R1 | `kill_switch` | Global switch: `off` / `full` (block everything) / `reduce_only` (allow only inferred closing orders) |
| R2 | `input_validity` | Order passes schema, version gate, currency consistency, finite amounts (violations → `exit 4`) |
| R3 | `max_order_quantity` | Single-order quantity limit |
| R4 | `max_order_value` | Single-order notional limit (options: price × multiplier × quantity) |
| R5 | `max_symbol_exposure` | Exposure per underlying (options by strike × multiplier × quantity) |
| R6 | `max_total_exposure` | Portfolio gross exposure ratio |
| R7 | `cash_margin_check` | Post-trade cash floor and short-option margin |
| R8 | `max_daily_loss` | Daily loss ratio (PnL / day-start equity) |
| R9 | `max_drawdown` | Drawdown ratio from peak |
| R10 | `order_time_validity` | Order age / future timestamps (unparseable → fail-closed BLOCK) |
| R11 | `data_freshness` | Portfolio snapshot freshness (future snapshot → fail-closed) |
| R12 | `missing_data_fail_closed` | Missing/null/ill-formed portfolio data → `exit 3` (data unusable = risk) |

Optional rules (R3–R7) are toggled by their config keys in `policy.yaml`; a missing
optional key must be declared in `acknowledged_disabled` or the policy is rejected
(`exit 4`). Mandatory rules (R1, R2, R8–R12) can never be disabled.

## Exit codes

| Code | Meaning |
|---|---|
| `0` | PASS — the order is allowed as given |
| `2` | WARN — proceed only if your execution policy explicitly allows warnings |
| `3` | BLOCK — the order must not be submitted (risk rule or fail-closed data) |
| `4` | Input / configuration error — the caller misused the API, not a risk event |
| `5` | Internal / rule exception — treated as BLOCK (fail-closed) |

In shadow mode the internal verdict is recorded (`shadow_verdict`) while the
external projection is `PASS / 0`; kill-switch hits and `exit 4/5` are never
projected away.

## Data contracts & migration

Schemas are versioned JSON Schema 2020-12 files shipped inside the package:
`order`, `portfolio`, `policy`, `result`, `audit-record`, `shadow-report`.
Explicit offline migration is avai