feat(brokers): give the port an idempotency key so a placement retry is safe

[eaitbrahim]

Closes #409.

The defect

Every adapter minted a fresh uuid4 client_order_id per place_order call, so no retry was ever deduplicated. A caller retrying after a timeout — exactly when the first request may already have reached the venue — placed a second live order, because the retry carried a different id and the venue had nothing to match it against.

Robinhood and Alpaca documented the hazard. Coinbase's docstring asserted the opposite:

Place a live order. A fresh client_order_id per call gives Coinbase idempotency.

That had it backwards. A per-attempt id is precisely what withholds idempotency — it leaves the venue nothing to deduplicate on.

Why it stayed a comment

The port could not express the difference. place_order(spec) cannot tell a retry of one intent from two orders a strategy genuinely meant to place. So the port now carries it:

def place_order(self, spec: OrderSpec, *, idempotency_key: str | None = None) -> PlaceResult

• None mints per attempt — the unchanged default. The opposite default is not safer: an id derived from the order would collapse two deliberate orders into one, and a position at half the intended size is as wrong as one at twice it.
• A key resolves every attempt under it to one venue-facing id.

The derivation, and why it hashes

keel_broker_api.port.resolve_client_order_id owns it, and turns the key into a uuid5 rather than passing it through:

resolve_client_order_id(None)                      # -> a fresh uuid4, one per attempt
resolve_client_order_id("cycle-7:pos-3:exit")      # -> the same uuid5, every time

The venues do not agree on what a client order id may be — Robinhood's is a UUID, Alpaca's a string of up to 128 characters. Hashing lands on the intersection, so a caller uses whatever natural key it has (a cycle id, a position id, a leg name) without knowing which venue the order will be routed to. One derivation in one place: an adapter inventing its own rule would make the same key mean different orders at different venues.

uuid5 is deterministic across processes, which is the case that matters. A retry issued by a new process — what a crash produces — derives the same id as the attempt that crashed. An in-memory table of "ids I already sent" cannot cover that.

The namespace is pinned by a test that writes the expected UUID out rather than recomputing it from the implementation. Recomputing would pass just as happily if the namespace changed, and a changed namespace silently makes every previously-derived id unreachable — which is the deduplication this mechanism exists to provide.

Threading

adapter
robinhood	key → to_order_body(client_order_id=...)
coinbase	key → create_order(client_order_id=...), backwards docstring corrected
alpaca	key → to_order_body(client_order_id=...)
fake	accepts and deliberately ignores — it has no client_order_id to carry it into, and a dedup table there would make the stand-in behave better than the venues it stands in for

Conformance

Two new contract tests. They assert acceptance, and that a repeat under one key still reaches the adapter — not deduplication, which is the venue's behaviour and cannot honestly be claimed by a suite running on canned transports. The second one also pins that an adapter must not remember keys locally and refuse the repeat: deduplication belongs to the venue, the only party that knows whether the first attempt actually landed.

Scope

This does not add retries anywhere. It makes one possible. #411's create_order backoff was blocked on exactly this — retrying a POST without an idempotency key doubles live orders — and is now unblocked.

Full suite: 3684 passed, 3 skipped. ruff check and mypy (189 files) clean.

🤖 Generated with Claude Code