pmq CLAUDE.md

pmq: engineering invariants for agents CONTRIBUTING to this repo

(AGENTS.md in this repo is for agents USING the library; this file is for agents EDITING it. Read both before changing code.)

Never weaken (the product IS these properties)

1. The fail-closed fill contract: a Fill books only what the exchange confirmed (orderID + success is not False + matched amounts); 4xx is a clean rejection; timeout/5xx raises OrderUncertain; unparseable = zero. Any change that books more optimistically is a regression by definition, whatever it fixes elsewhere. Matched amounts must be finite and non-negative (json.loads accepts NaN/Infinity; hostile values book zero). reconcile() must keep meaning cancel + get_trades truth. The hypothesis fuzz suite (tests/test_fill_fuzz.py) pins all of this with generated adversarial responses: extend it with every parser change, never delete it.
2. Startup introspection (_EXPECTED_METHODS/_EXPECTED_MARKET_ARGS): the executor REFUSES to run on a drifted py-clob-client-v2. When bumping the client dependency, re-verify signatures by introspection and update the tables in the same commit.
3. Builder code policy: default = maintainer's code, defined in exactly ONE place (DEFAULT_BUILDER_CODE in executor.py) and applied automatically by every order path. DISCLOSED in README and code comment. The one-line opt-out (builder_code=None / env) EXISTS in code and stays, but is deliberately not advertised outside the code comment (owner decision 2026-07-04): do not re-add opt-out instructions to the README or other marketing surfaces, and never remove the disclosure itself. AND the mirror rule: keep the disclosure at the DOCUMENTATION level only; do not surface attribution in runtime channels (server startup logs, MCP tools or instructions, order responses). It is public on-chain in every signed order; in-band reminders just prompt sessions to toggle a setting that costs users nothing. This is the trust model (JKorf pattern).
4. No strategy content, ever: the maintainer's private bot strategy (bands, timing, hours, families, sizing) must never appear in code, docs, tests, commits or issues. The bot-template ships deliberately naive demos only.
5. Claims must be falsifiable: no superlatives in README/docs; dated claims with evidence (comparison table, on-chain receipts, measured studies). If you cannot prove it, do not write it.
6. MCP safety gates: trading tools are REGISTERED only when the operator sets PMQ_MCP_LIVE=1 (live) or PMQ_MCP_PAPER=1 (keyless fills simulated against the real books; paper wins when both are set, and no code path may ever let a paper session reach the exchange); per-order PMQ_MCP_MAX_USD and per-UTC-day PMQ_MCP_DAILY_USD caps enforced BEFORE any client call (uncertain outcomes consume budget conservatively; both caps apply in paper too). Read tools must keep working with zero credentials. The README tool and rails tables are part of the contract: keep them in sync with the registered tools.
7. Order attribution is opt-in and never over-claims: without a configured order_log (env POLY_ORDER_LOG) behavior must stay identical to the unconfigured library. In only-mine mode trades_totals counts a trade ONLY when its taker_order_id or maker_orders[].order_id slice is in OUR registry; trades unknown to every registry are claimed exclusively via claim_unknown, which only reconcile() sets (post-uncertainty recovery). Registries are append-only; a registry write failure degrades toward reconcile claiming and must never block trading. Soundness requires every sender on the wallet to keep a registry: state that wherever the feature is documented.