Honor passive (post-only) order intent on the typed CreateOrder path

[outerlook]

Problem

The typed CreateOrder path silently drops post-only intent. Clients already send
orderIntent: "passive_only", but CreateOrderPayloadSchema has no such member and the
zod object is not strict, so the key is stripped and the order reaches the venue as a plain
LIMIT GTC. A "passive" order can therefore cross the book and execute as taker.

This is not theoretical. Over 14 days of live market-making orders, 17% of filled base
volume on one pair and 38% on another executed as taker despite being authored as
post-only maker rungs. The cost is execution price — crossing the spread against our own
stale quote — not fees.

Change

Implements the broker half of the passive-order contract that the clients already speak:

• CreateOrderPayloadSchema accepts an optional orderIntent: "passive_only". Unknown
  values now fail validation instead of being silently ignored — the silent strip was the
  bug.
• With that intent, the handler requires a limit order, sets postOnly: true in the ccxt
  params without clobbering caller-supplied params, and returns
  passivePlacementOutcome: "accepted_passive".
• Venue failures map onto the existing error codes passive_order_would_cross,
  passive_order_unsupported, and passive_order_rejected, classified in one place
  (src/helpers/passive-order.ts) and given stable gRPC statuses.

Classification is deliberately conservative: it identifies would-cross only from ccxt's
OrderImmediatelyFillable or explicit immediate-execution wording, and unsupported only
from explicit signals. Anything ambiguous becomes passive_order_rejected — never success.

When orderIntent is absent the request and response are unchanged; each addition sits
behind a conditional spread, and a test asserts the ordinary path byte-for-byte.

passiveOnly capability advertisement was skipped: this service has no general
venue-capability surface to expose it on.

Deploy ordering

This must reach production before the corresponding client change. A client that
requests passive_only against a broker that omits passivePlacementOutcome fails every
such order closed. Broker first, then client — never together.

Verification

bun test          474 pass, 0 fail (41 files)
bun run build:ts  exit 0
bun run lint      exit 0 (pre-existing repo-wide warnings only)

New tests cover the unchanged ordinary path, param preservation, a conflicting caller
postOnly, passive market-order rejection, unknown-intent schema rejection, and each of
the three venue failure classifications.

Summary by CodeRabbit

• New Features

  • Added support for passive-only limit orders.
  • Passive orders are automatically submitted as post-only and report their accepted placement outcome.
  • Added clear handling for unsupported, rejected, and immediately executable passive orders.
  • Added validation to reject passive market orders and invalid order intents.

• Bug Fixes

  • Improved error status mapping for passive-order failures.

• Tests

  • Added coverage for passive-order validation, submission behavior, responses, and error handling.

[outerlook]

Client half: usherlabs/fiet-maker#941. This PR must deploy first — a client requesting passive_only against a broker that omits passivePlacementOutcome fails every such order closed.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 49 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7c9fa95b-aa76-44b2-a25c-9731e54f0da3

📥 Commits

Reviewing files that changed from the base of the PR and between 1bc7df1 and 6ad5240.

📒 Files selected for processing (2)

• src/handlers/execute-action/orders.ts
• test/passive-order.test.ts

Walkthrough

Passive-only intent is added to order payload validation. Limit orders force postOnly, successful responses identify accepted passive placement, and exchange failures receive passive-specific classification and stable gRPC status mappings.

Changes

Passive order support

Layer / File(s)	Summary
Passive intent and error contracts src/schemas/action-payloads.ts, src/helpers/passive-order.ts	The payload accepts passive_only, while exchange errors are classified as would-cross, unsupported, or rejected.
Passive order handler flow src/handlers/execute-action/orders.ts, src/helpers/grpc/status.ts	Passive orders are restricted to limit orders, submitted with postOnly: true, marked as accepted on success, and mapped to stable gRPC errors on failure.
Passive behavior validation test/passive-order.test.ts, test/grpc-status.test.ts	Tests cover parameter handling, validation, success responses, error classification, and gRPC status mappings.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant CreateOrder
  participant CCXT
  participant gRPC
  Client->>CreateOrder: Submit passive_only limit order
  CreateOrder->>CreateOrder: Validate order intent and type
  CreateOrder->>CCXT: createOrder with postOnly true
  CCXT-->>CreateOrder: Accepted order or exchange error
  CreateOrder->>gRPC: Return accepted_passive or classified error

Loading

Suggested reviewers: csmithington

Poem

A bunny placed a limit with care,
Post-only magic in the air.
If crossing clouds began to form,
Errors wore a stable form.
“Accepted passive!” carrots cheer—
Clean order paths hop proudly here.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding passive post-only intent support to the typed CreateOrder path.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/passive-order-intent

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/handlers/execute-action/orders.ts`:
- Around line 201-207: The passive-order classification in the surrounding
execution catch must apply only to failures thrown by broker.createOrder. Narrow
the try/catch or error-routing logic around broker.createOrder so resolution,
metadata capture, telemetry, and archive failures retain generic handling, while
actual venue submission failures still use classifyPassiveOrderError and
rejectWithGrpcError; add a regression test covering a non-submission failure and
preserving the already-placed-order behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3cf8be54-e1d1-4c92-806a-120ea7329d48

📥 Commits

Reviewing files that changed from the base of the PR and between 0d0b70b and 1bc7df1.

📒 Files selected for processing (6)

• src/handlers/execute-action/orders.ts
• src/helpers/grpc/status.ts
• src/helpers/passive-order.ts
• src/schemas/action-payloads.ts
• test/grpc-status.test.ts
• test/passive-order.test.ts

📜 Review details

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2026-04-14T06:47:01.283Z

Learnt from: csmithington
Repo: usherlabs/cex-broker PR: 38
File: src/client.dev.ts:0-0
Timestamp: 2026-04-14T06:47:01.283Z
Learning: In this codebase, gRPC action constants such as `FetchTicker`, `FetchFees`, and `FetchAccountId` should be sourced from `src/helpers/constants.ts` and imported from there (e.g., used by both `src/client.dev.ts` and `src/server.ts`). Do not import or reference generated proto TypeScript artifacts (for example `./proto/cex_broker/Action`), since those generated files are git-ignored and won’t be available/committed consistently.

Applied to files:

• src/helpers/passive-order.ts
• src/helpers/grpc/status.ts
• src/schemas/action-payloads.ts
• src/handlers/execute-action/orders.ts

🔇 Additional comments (6)

src/schemas/action-payloads.ts (1)

78-80: LGTM!

src/helpers/passive-order.ts (1)

1-55: LGTM!

src/handlers/execute-action/orders.ts (1)

13-13: LGTM!

Also applies to: 51-172

src/helpers/grpc/status.ts (1)

21-29: LGTM!

test/passive-order.test.ts (1)

1-219: LGTM!

test/grpc-status.test.ts (1)

24-32: LGTM!

[outerlook]

Addressed in 6ad5240.

The finding was valid: the catch covers the whole execution block, so policy resolution and market-metadata capture failures were being reported to the client as passive_order_rejected — an infrastructure fault dressed up as a venue answer.

Classification is now gated on a submission state that is in_flight only across the broker.createOrder call itself. Failures before it never reached the venue and keep generic INTERNAL handling; failures after it mean the order is already resting, and a passive code there would tell the client its order was never placed and invite a duplicate repost. Both directions have regression tests (pre-submission via a market-resolution failure, post-submission via a serialization failure after a successful placement), asserting createOrder call counts and that no passive_order_* code is emitted.

Full suite: 476 pass, 0 fail. Typecheck and lint clean.

Not changed, and worth naming: a network timeout on the submission itself is still classified passive_order_rejected while the order may in fact have reached the venue. That ambiguity is a property of the existing error contract rather than something introduced here, so it stays out of this PR.