Repository navigation
Paper-only execution-capacity harness for Alpaca order actions (rate-limit-adaptive, websocket state) - #165
Merged
Conversation
blueprints/us-equities/order-throughput measures sustained order actions (REST submits + individual cancels) per 60 s on an Alpaca paper account, with order state taken from the trade_updates websocket and a bounded REST reconciliation at the end. It is an execution-capacity qualification only: probes are non-marketable 1-share limit BUYs below the bid, cancelled individually, and receipts state they are never strategy trades. - rate_governor: budget = floor(min(cap, observed trading x-ratelimit-limit) * headroom); token bucket + rolling 60 s cap + x-ratelimit-remaining/reset reserve; 429 freezes and backs off per Retry-After/reset/exponential; a rising header lifts the budget up to the cap (same code at 200 and 1000). - capacity: engine, bounds, STOP (adaptive-paper DEFAULT_STOP), account lock, adaptive-lane conflict guard, acknowledged-exposure refusal, cancel-all guard (off by default), cleanup on exit/signal/exception with verified zero open harness orders, reconciliation, receipt and CLI. - alpaca_capacity_port: native paper port reusing adaptive-paper transport (GuardedSession, preflight, trade_updates stream class) read-only. - capacity_fixture: offline fake clock/broker/stream (offline_fixture). - rate-limit-evidence-20260924.json (+ rate_limit_evidence.py --check): cited limits, 419 trading:200 / 9 data:10000 headers measured from the retained trial outputs, and submit/cancel/round-trip arithmetic. Tests: tests/test_order_throughput.py (44 offline tests). The native port has not been run against Alpaca or the pinned SDK in this change. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Fixes from review of the paper execution-capacity harness: - _collect records a failing in-flight future instead of raising, so cleanup always sends cancels, sweeps by prefix and verifies; a failed submit becomes ambiguous and the first port defect fails the run. - Cleanup's deadline is 60 s of unfrozen time: a 429 backoff extends it up to a hard ceiling (timeout + 3 x max backoff), with up to 3 sweep/verification rounds; failing steps are recorded, not fatal. - Every page of an order listing is admitted by the governor (list_orders takes an admit callback in the native port and fixture). - Sustained capacity counts only completed order actions (2xx submits and cancels); attempted actions are reported separately. - Websocket completeness includes orders the final broker listing proves existed, e.g. an ambiguous submit whose order was created. - acceptance.passed requires the frozen criteria (>= 5 windows, ratio >= 0.85) and no health freezes; it is marked self-reported and the README requires an independent observation for native acceptance. - A 0600 exclusive JSONL journal (prefix fsynced before any order, intents before each POST) plus recover/audit commands for crash recovery. - Receipt provenance: git revision, source hashes, SDK and Python versions, sanitized argv, end time and exit code. - Stream and REST completion times are stamped on their own threads; the quote refresh runs on a worker. - The session reserve covers stream start, the cleanup ceiling, reconciliation and a margin. - The script entry point runs through the importable module, so the ports' capacity.Response is the engine's class (as __main__, completed actions were uncounted and sweep cancels failed). Tests: 60 offline tests (16 new), including multi-inflight out-of-order completion, a real ThreadPoolExecutor, a created order with a lost response, crash then journal recovery, and the script entry point. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6b57b9303a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…ght, full Retry-After - Reconciliation compares the whole nonzero-position snapshot with the preflight (all_positions_unchanged, changed_position_symbols), not only the probe symbol. - Quotes carry ts_ns from normalize_quote; a missing, stale (>60 s, max_quote_age_seconds) or future-dated quote refuses the run, and a stale refresh freezes submissions. - recover uses a trading-only recovery_preflight (GET /v2/account) so a market-data outage cannot block cancelling a crashed run's orders. - Broker-designated Retry-After/x-ratelimit-reset delays are honoured in full; max_backoff caps only the exponential fallback, and a longer broker delay stops submissions (rate_limit_backoff_exceeds_max). - README cites the Trading API reference for after_order_id and states the max_http_429 tolerance semantics. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This was referenced Sep 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
blueprints/us-equities/order-throughput/, a paper-only execution-capacity harness for Alpaca order actions. It measures how many order actions per minute the paper account sustains. It generates no strategy trades: the adaptive-paper README says "no strategy manufactures trades to hit a throughput target", and its orders are never counted as trades.What it does
floor(min(cap, trading x-ratelimit-limit) × 0.9). The limit is read from a preflight call to the trading endpoint only, so the market-data endpoint's 10000 limit never sets it. A token bucket, a hard rolling 60 s count and a remaining/reset guard all apply. A 429 freezes all calls and backs off using Retry-After, then the reset time, then exponential delay. The same code runs at 200/min and at 1000/min once the header rises (for example on Elite or a non-retail account).trade_updateswebsocket. REST calls are spent on submits and cancels, with one bounded reconciliation at the end. Ambiguous submits are never resent.GuardedSession, which allows DELETE only on/v2/orders/{uuid}. The code path exists only behind a proven-no-foreign-orders guard.safety.DEFAULT_STOP. It holds the adaptive-paper account lock, and it refuses to start while unacknowledged positions or orders exist or adaptive-paper trial state is present. Totals, duration, open orders and notional are capped. Cleanup always runs.rate-limit-evidence-20260924.jsonrecords:Evidence class: offline fixture only. No Alpaca call was made.
adaptive-paper/requirements.txt: Python 3.12.3, nautilus-trader 2.0.0rc5 and alpaca-py 0.44.0.tests.test_order_throughput: 60 OK.test_adaptive_*: 671 OK (skipped=1). With the SDK present, 191 formerly skipped tests now run.scripts/validate.pyandvalidate_catalogs.pypass.test_effort_default_guard.test_shipped_guard_is_verbatim, caused by a stale~/.claudehook. It also fails on plain main.Review. Two independent read-only reviewers covered broker side effects and safety, and correctness and measurement validity. They raised 12 findings, one of them high: an action was counted when dispatched, not when its outcome was known. All were fixed in
6b57b93, with 16 new regression tests.Not yet done
native_paperreceipt. The first run needs a private paper credential file on the running host.🤖 Generated with Claude Code