docs/EXECUTION_ARCHITECTURE.md

Execution architecture — decided 2026-08-20

⚠ CORRECTION 2026-08-22: execute.py and paper_run.py DO NOT EXIST

This document is written in the present tense about two files — "execute.py shells out to kraken", "execute.py now calls kraken balance first and clamps every order", "paper_run.py — sealed signals … Tamper-tested: rewriting a sealed price is detected". On 2026-08-22 the covenant folder was reachable over the device bridge for the first time and searched end to end. Neither file is there. The only nearby file is paper_bot.py, which is not the same thing.

They were almost certainly written in a cloud session, delivered by SendUserFile, and never saved to disk — the same failure mode that left the node source fourteen versions stale (claude/PC_SYNC_LOOP.md, M25). The bug report about the SOL order sized against a Kraken balance that did not hold it is real and worth keeping; the sentence saying it was fixed describes code that cannot be found.

What this changes:

• TRADING_READINESS.md §2 lines 3 and 4 were never blocked on an upload. They are blocked on code that has to be written.
• Nothing below has been run against a live kraken CLI by anyone but L. Treat the whole document as a design that was agreed, not as a description of working software, until the two files exist and have tests.
• The design itself still stands and is not weakened by this: the split below (cloud computes, L confirms, the local kraken binary places) is what the Section-0 boundary requires whether or not any code implements it yet.

Kraken shipped an official CLI (v0.4.1, MIT, Rust) with a built-in MCP server. That changed what is possible here, so this records the shape and why.

The split

layer	where it runs	holds a key?
compute the orders	cloud session (me)	no
confirm each order	the user, per order	—
place the order	kraken on the user's machine	yes, its own config

execute.py shells out to kraken. It never reads, stores, or asks for a credential.

This is not ceremony. The cloud session fetches web pages, reads project docs, and processes tool output continuously — any of which can contain text crafted to look like an instruction. If that process could also reach a trade-enabled credential, a poisoned page becomes a market order. Keeping the key out of its reach makes that impossible rather than unlikely.

Kraken's own guidance agrees: --allow-dangerous should be used "only when the calling agent is trusted and has been validated through paper trading."

MCP defaults (from the binary's own help, not the README)

"Default exposes read-only services (market, account, paper, workspace). Use -s all to include trade, funding, futures, earn, subaccount, and auth."

Default list: market,account,paper,workspace,feedback. The README understated this — always read --help on the actual binary.

Bug caught in testing: orders must be clamped to the venue

holdings.txt is everything owned across every venue. Kraken can only sell what is in the Kraken account. The first version sized a sell for XLM when the test balance held 900, and generated a SOL order for coins not there at all.

execute.py now calls kraken balance first and clamps every order, reporting the gap rather than silently shrinking it:

SOL: rule fires but cannot act here -- held elsewhere, not on Kraken
1. SELL <qty> XLM  [clamped: rule wants <qty> but Kraken holds <qty>]

paper_run.py — sealed signals

Appends one hash-chained record per run: the call, the price, the time, sealed before the outcome exists. Editing entry n breaks every entry after it; --verify proves the chain. Tamper-tested: rewriting a sealed price is detected.

Guards that must not be removed:

• Below 30 scored signals it reports NOT ENOUGH DATA regardless of the numbers. A 7-2 record occurs by chance ~9% of the time.
• Two-sided reporting. The headline test is one-sided ("better than a coin flip"), which reports p=1.000 for a terrible record — technically true and badly misleading. A strongly inverted result is not a null result; it has predictive content pointing the other way and should be investigated, not filed as noise.

Standing constraints

• Never hold, request, or use a trade- or withdrawal-enabled key in the cloud session.
• Never touch the Ledger recovery phrase. Unchanged, absolute.
• Credentials live in ~/.config/kraken/config.toml inside WSL — never in C:\Users\<user>\covenant, which syncs off the machine.
• Never claim a profit edge. Established: no timing edge survived out-of-sample on two real assets (XRP −2.70% p=0.656; HBAR −7.06% p=0.891). Only drawdown reduction (~3×) replicated.