Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 17 additions & 2 deletions blueprints/us-equities/adaptive-paper/README-safety.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,11 +62,26 @@ limit-order mechanism guarantees a flat finish.
that no HTTP request was sent; a timeout or other ambiguous send must remain
unresolved and be queried by its existing client ID. Observed orders cannot
be marked not sent, and a later broker observation of such an ID fails closed.
- `mark_broker_refused(client_id, http_status)` records distinct local terminal
- `mark_broker_refused(client_id, http_status, refusal=None)` records distinct local terminal
status `broker_refused` for an attempted zero-fill order without broker ID.
Only HTTP 401/403/404 qualify, and transport must first establish that the
subsequent client-ID lookup returned 404. It retains the HTTP status and budget.
Timeout, 400, 422, 429 and 5xx remain ambiguous. Neither local terminal status is
Timeout, 400, 422, 429 and 5xx remain ambiguous, with one exception that Alpaca's
documentation proves definitive: a 422 whose `refusal` is `SUB_PENNY_REFUSAL`
(`"sub_penny_minimum_price_variance"`), which the transport assigns only to the
documented body code 42210000 with "sub-penny increment does not fulfill minimum
pricing criteria" (https://docs.alpaca.markets/us/docs/orders-at-alpaca.md: such
orders "will be rejected"). That page documents the body, not the HTTP status;
the 422 was inferred from the code prefix and the POST /v2/orders 422 entry. It
was observed once on the paper endpoint in the 2026-09-24 native-fault run
(`native-faults/receipt.json`, C04: submit 422, then lookup 404). The same body
under any other status still stays ambiguous. The message, not the code, is the discriminator. The ledger also requires the intent's own durable
limit price to violate the minimum price variance (`refusal_contradicts_intent_price`
otherwise). Any other 422, including "client_order_id must be unique", stays
ambiguous. `reserve_intent` still refuses such a price before send
(`invalid_price_increment`, via the overridable `_check_price_increment`); only
the native-fault harness's `FaultLedger` exempts its single C04 client ID.
Neither local terminal status is
adopted or looked up as a broker order on restart; any later broker observation
of the identity fails closed.
- `record_order(client_id, broker_id, status, cumulative_qty, average_price, *,
Expand Down
30 changes: 26 additions & 4 deletions blueprints/us-equities/adaptive-paper/README-transport.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,10 +40,32 @@ the caller's recovered durable intents. A repeated ID is looked up, never posted
again. Broker 401/403/404 refusals with a confirming absent-ID lookup, and a
locally prevented request, expose `definitive_rejection=True`. A 400 or 422 may
mean a duplicate ID whose earlier order is not visible yet; it remains ambiguous
unless lookup resolves the frozen intent. Ambiguous errors retain unresolved
state, freeze admission, and perform at most one lookup without resubmission.
Cancellation acknowledgements are followed by a lookup, not treated as fills or
terminal cancellations. All observations contain cumulative quantities; stream
unless lookup resolves the frozen intent. The one exception is Alpaca's documented
minimum-price-variance refusal: a 422 whose body code is 42210000 and whose message
contains "sub-penny increment does not fulfill minimum pricing criteria", for a
first POST whose limit price really has more than two decimals at or above $1.00
(four below), followed by an absent-ID lookup. Alpaca states such orders "will be
rejected" (https://docs.alpaca.markets/us/docs/orders-at-alpaca.md). That page
documents the body but not the HTTP status. 422 was inferred from the code prefix and
the POST /v2/orders 422 entry. It was observed once on the paper endpoint in the
2026-09-24 native-fault run (`native-faults/receipt.json`, C04). The message, not the
code, is the discriminator. The transport
raises `RejectedSubmission(422, "sub_penny_minimum_price_variance")` and compares
the body with those constants only, never retaining or raising it. The engine's
own Ledger refuses such prices before send, so only the native-fault harness,
which exempts its single C04 client ID, can reach this path. Ambiguous errors
retain unresolved state, freeze admission, and perform at most one lookup without
resubmission. `cancel()` sends the DELETE for every owned order: to the broker ID
it already observed, or, with no observation, to the ID a client-ID lookup
returns. It does not skip the DELETE because a cached or freshly read status is
terminal; the caller asked because it believes the order open or ambiguous. The
answer is data: 204 is only an acknowledgement; 404 or 422 ("The order status is
not cancelable",
https://docs.alpaca.markets/us/reference/deleteorderbyorderid-1.md) is accepted
without a freeze when the follow-up lookup shows the order terminal, and freezes
`cancellation_unresolved` otherwise; a timeout, 429 or 5xx freezes as before. Every
DELETE is followed by a lookup, never treated as a fill or terminal cancellation,
and repeating a known terminal observation changes no ledger state. All observations contain cumulative quantities; stream
observations additionally retain available execution IDs and individual event
quantity/price. Consumers must deduplicate executions and never manufacture
individual fills from a cumulative REST snapshot.
Expand Down
Loading
Loading