deadman

Installs as deadman-kit (pip install deadman-kit), imports as deadman — the PyPI name deadman was taken.

deadman sits between your strategy and your broker, and when it meets the unknown it stops instead of guessing.

Execution-safety primitives for automated trading systems. Zero runtime dependencies. Broker-agnostic, strategy-agnostic. Every claim below has a test or a spec section behind it — the links are the argument.

Specification: docs/SPEC.md (v0.1, closed 2026-08-18; written before the code). Conformance statement, exact: 11 of 13 test groups implemented, 165 collected cases (164 pass, 1 platform skip with its reason in the test), 2 elements declared out of scope with rationale — see SPEC §6b. Not "13/13".

What it is not — said first, without shame

deadman does not bring a strategy, signals, a market-data feed, a broker connection, position sizing, paper accounting, or any notion of your account's equity. You pass it a BrokerPort adapter (five methods, guarantees G1–G9) and an Intent; it returns allowed/denied with a code, and — if asked — runs the post-fill sequence honestly. Everything it needs to decide it receives in the call. Nothing it needs is guessed.

Threat model, in plain words

• The external anchor is the guarantee: the ledger tip (seq, hash) is published to a third party the operator does not control. Everything before the latest anchor is dated by that third party and provably unchanged.
• The local hash chain is the mechanism: it detects corruption, partial writes, buggy rewrites, deletions, reordering, broken rotation — and it is what lets 64 bytes cover the whole history.
• Signing is optional and the key is yours (signer/verifier callables). With the key on the same disk as the ledger, a signature adds nothing over the chain; the library does not pretend otherwise.

The two tests that show the library's own limit, next to each other: test_full_rewrite_with_recompute_passes_the_chain_alone — an attacker with disk access rewrites an entry, recomputes the chain to the tip and replaces the tip file: the chain verifies — and test_same_rewrite_is_caught_by_an_external_anchor — the same rewrite, plus the attacker wiping the local anchors file, is caught by verify(anchors=…) with the anchors held by the third party (ANCHOR_MISMATCH).

What counts as a third party (SPEC §2b): a git branch protected against force-push and deletion for everyone including the owner, or an RFC 3161 timestamp authority, or a third-party append-only service with server-side timestamps. A remote you can force-push is not one — the anchor is then worth nothing over the local chain. Sustained publisher failure is not silent: ANCHOR_STALE in the ledger + a visible anchor_stale.flag, recovered by the next success (test test_sustained_anchor_failure_raises_stale_flag_and_recovers). An example publisher (git push to a protected branch) is in examples/ — it is your code; the library never touches the network.

The primitives, each with the bug that motivated it

These are patterns from a real system, kept as patterns. They are the reason the library exists.

The principle behind all of it — zero plausible defaults — is a contract, not a slogan: SPEC §2.

What this library does not protect against

This section is what makes the rest credible.

• A deliberate rewrite of the ledger by someone with disk access, when no external anchor covers it. The chain alone verifies after a recompute — proven, not hidden: test_full_rewrite_with_recompute_passes_the_chain_alone. Only an anchor held by a real third party catches it (test_same_rewrite_is_caught_by_an_external_anchor), and only for history before that anchor.
• Anything after the latest anchor. The window equals your anchoring interval; that is why anchors are forced after halts, unknowns and kill events (test_anchor_forced_after_safety_events_and_by_count).
• A remote you can force-push. It is not a third party; see above.
• Two writers racing on a state file. Not prevented (no OS lock on halt/stats in 0.1) — detected and escalated to a halt (G13).
• A broker adapter that lies. BrokerPort guarantees G1–G9 are the adapter's job; if fetch_order invents "closed" for an unmappable state, or fetch_order_by_client_id returns None without being authoritative, deadman will believe it. The conformance tests (tests/fake_broker.py is the reference shape) are how you check an adapter.
• Your account and your sizing. deadman has no equity, no positions of its own, no snapshot of your account. size_available is whatever you pass; a stale balance you pass as fresh is your stale balance (SPEC G8 is out of scope for this reason — SPEC §6b).
• Losing money. It stops you from acting on what it cannot vouch for. It does not know whether your strategy has an edge.

Quickstart (honest: this is the whole flow)

from deadman import (Paths, SystemClock, WriterIdentity, Ledger, KillSwitch, EntryHalt,
                     DailyLimits, Limits, OrderSanity, HonestExecutor, Intent, spot_long_only_is_exit)

clock = SystemClock()
paths = Paths("/var/lib/mybot/deadman")            # one explicit root for every state file
ident = WriterIdentity(clock)

ledger = Ledger(paths, clock, publisher=my_publisher)   # my_publisher: see examples/git_anchor_publisher.py
kill   = KillSwitch(paths, ledger)                       # `touch /var/lib/mybot/deadman/kill_switch.enabled` stops everything
halt   = EntryHalt(paths, clock, ident, ledger)
halt.startup_check()                                     # another live process owns the halt file? -> loud
limits = DailyLimits(paths, Limits(max_trades_per_day=20, max_daily_loss_usd=50.0, worst_case_fee_bps=80.0),
                     spot_long_only_is_exit, clock, ident, ledger)
sanity = OrderSanity(allowed_symbols=frozenset({"BTC/USD"}), max_latency_ms=500, max_spread_bps=20)

ex = HonestExecutor(my_broker_port, kill, halt, limits, sanity, ledger, spot_long_only_is_exit, clock,
                    fill_timeout_s=10.0, poll_interval_s=1.0)
report = ex.startup(["BTC/USD"], position_of=lambda sym: None)   # reconcile BEFORE any intent; halts if it finds anything

intent = Intent(symbol="BTC/USD", side="buy", units="USD", amount=25.0, kind="ENTRY", client_id="sig-2026-08-18-001")
result = ex.execute(intent, price=64_000.0, broker_status="connected", latency_ms=42.0,
                    bid=63_995.0, ask=64_005.0, size_available=1_000.0)
print(result.status, result.code, result.reason)   # FILLED | PARTIAL | NO_FILL_CANCELED | DENIED | UNKNOWN
print(ledger.verify())                              # the ledger alone explains every final state

my_broker_port is your adapter implementing BrokerPort (five methods). my_publisher is your anchor publisher. Neither is provided: the library does not talk to the network.

Install and test

pip install deadman-kit        # installs as deadman-kit, imports as deadman; zero runtime dependencies
python -m pytest -q tests   # 165 cases; Windows, Linux, macOS in CI

CI: .github/workflows/deadman.yml — ubuntu/windows/macos × Python 3.10/3.12/3.14, plus a job that builds the wheel, installs it into a clean venv with --no-deps and runs a smoke flow. Windows is not optional there: the msvcrt.LK_NBLCK finding (LK_LOCK gives up with an OSError that is not a PermissionError) is a claim only a Windows run keeps honest.

License

MIT. See LICENSE. Changes: CHANGELOG.md.