gloomberb 0.18.3 → 0.18.5

package/src/plugins/builtin/broker-trading/controller.ts

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../utils/log-failure";
 import { matchesNumberStep } from "../../../components/ui/number-step";
 import type { BrokerAdapter, BrokerConnectionStatus } from "../../../types/broker";
 import type { BrokerInstanceConfig } from "../../../types/config";
@@ -5,6 +6,7 @@ import type { Quote } from "../../../types/financials";
 import type { BrokerAccount, BrokerOrder, BrokerOrderPreview, BrokerOrderRequest, BrokerTradingCapabilities } from "../../../types/trading";
 import { optionContractIdentity } from "../../../utils/options";
 import { isStrategyOrder, strategyQuote } from "./strategy";
+import { checkLinkedOrder, restingEntryPrice } from "./linked-orders";
 import { brokerOrderDone, brokerOrderStatus, orderEstimatePrice, ticketEditingPriceStep } from "./orders-data";
 
 export interface BrokerTradingContext {
@@ -84,6 +86,7 @@ const STREAM_QUOTE_MAX_SILENCE_MS = 75_000;
 const uncertainPlacement = "Outcome unknown. Check open orders before placing it again.";
 /** A change or cancel whose answer was lost: the views ask the broker until it says. */
 const uncertainChange = "Outcome unknown. Checking with the broker.";
+const orderReadFailed = "Order status could not be read. Showing the last known order.";
 /** The broker's own words come first: they say more than "outcome unknown". */
 const uncertainAfter = (error: unknown) => error instanceof Error && error.message && !error.message.includes(uncertainPlacement) ? `${error.message.trim().replace(/\.?$/, ".")} ${uncertainPlacement}` : uncertainPlacement;
 /** The broker answered no, or nothing was sent (see BrokerAdapter.placeOrder): its one-line reason, else undefined. */
@@ -92,6 +95,8 @@ function refusal(error: unknown): string | undefined {
   return error.message.trim().replace(/\.$/, "") || "The broker refused this action";
 }
 
+/** Terms the broker sets with its figures, or for having none, that the user accepts on the review: never skipped. */
+function asksForConsent(preview: BrokerOrderPreview): boolean { return !!preview.disclosure || preview.impactSource === "unavailable"; }
 function copy<T>(value: T): T { return structuredClone(value); }
 function freeze<T>(value: T): T {
   if (value && typeof value === "object") {
@@ -226,7 +231,9 @@ export class BrokerTradingController {
     this.editable();
     const original = this.modifyOrder;
     if (original && (canonical(request.contract) !== canonical(original.contract) || canonical(request.legs ?? null) !== canonical(original.legs ?? null)
-      || request.action !== original.action || request.accountId !== original.accountId || request.orderType !== original.orderType || request.tif !== original.tif)) {
+      || request.action !== original.action || request.accountId !== original.accountId || request.orderType !== original.orderType || request.tif !== original.tif
+      // One order of a bracket or an OCO pair changes alone; a trailing stop keeps its unit.
+      || request.orderClass !== undefined || (request.trailingPercent !== undefined) !== (original.trailingPercent !== undefined))) {
       throw new Error("A modification keeps the original account, instrument, legs, side, type and time in force.");
     }
     // A spread's legs are its instrument: other legs need another quote.
@@ -275,15 +282,20 @@ export class BrokerTradingController {
     if (request.outsideRth && (!capabilities.extendedHours || (capabilities.extendedHoursTif && !capabilities.extendedHoursTif.includes(request.tif ?? "DAY")))) throw new Error("Extended hours are unavailable for this order and time in force.");
     const limit = request.orderType === "LMT" || request.orderType === "STP LMT";
     const stop = request.orderType === "STP" || request.orderType === "STP LMT";
-    for (const [needed, value, label] of [[limit, request.limitPrice, "limit"], [stop, request.stopPrice, "stop"]] as const) {
-      if (needed && !positive(value)) throw new Error(`Enter a valid ${label} price.`);
-      if (!needed && value !== undefined) throw new Error(`Remove the ${label} price for this order type.`);
+    const checkPrice = (value: number) => {
       const decimals = capabilities.priceDecimals;
-      if (value !== undefined && decimals !== undefined && (!Number.isInteger(decimals) || decimals < 0 || decimals > 18 || Number(value.toFixed(decimals)) !== value)) {
+      if (decimals !== undefined && (!Number.isInteger(decimals) || decimals < 0 || decimals > 18 || Number(value.toFixed(decimals)) !== value)) {
         throw new Error("Price precision exceeds the broker's limit.");
       }
-      if (value !== undefined && capabilities.priceStep !== undefined && !matchesNumberStep(value, capabilities.priceStep)) throw new Error("Price does not match the broker's allowed increment.");
+      if (capabilities.priceStep !== undefined && !matchesNumberStep(value, capabilities.priceStep)) throw new Error("Price does not match the broker's allowed increment.");
+    };
+    for (const [needed, value, label] of [[limit, request.limitPrice, "limit"], [stop, request.stopPrice, "stop"]] as const) {
+      if (needed && !positive(value)) throw new Error(`Enter a valid ${label} price.`);
+      if (!needed && value !== undefined) throw new Error(`Remove the ${label} price for this order type.`);
+      if (value !== undefined) checkPrice(value);
     }
+    // A bracket, an OCO pair or a trailing stop only where the broker runs it itself.
+    checkLinkedOrder(request, capabilities, context.adapter.describeInstance?.(context.instance).brokerName ?? context.adapter.name, checkPrice);
     return copy(request);
   }
 
@@ -355,7 +367,9 @@ export class BrokerTradingController {
       // The stream answered what a quote request could not.
       const answered = this.snapshot.error !== undefined && this.snapshot.error === this.quoteError;
       this.publish({ quote: value, loadingQuote: false, ...(answered ? { error: undefined } : {}) });
-    } catch { /* A quote that fails the checks leaves the last good one. */ }
+    } catch {
+      // Intentional ignore: invalid streamed quotes leave the last validated ticket quote in place.
+    }
   }
 
   /** A streamed quote for the current draft, still being pushed, stands in for asking. */
@@ -437,9 +451,9 @@ export class BrokerTradingController {
     this.entryPending = true;
     try {
       await this.prepareReview(fast);
-      // New risk information cannot be waived by a session preference.
+      // New risk information cannot be waived by a session preference, nor can the broker's terms.
       const review = this.snapshot.review;
-      if (fast && review && !review.requiresTypedConfirmation && !review.warnings.length && !review.preview.errors?.length) await this.submitReviewed(undefined, true);
+      if (fast && review && !review.requiresTypedConfirmation && !review.warnings.length && !review.preview.errors?.length && !asksForConsent(review.preview)) await this.submitReviewed(undefined, true);
     } finally { this.entryPending = false; }
   }
 
@@ -473,6 +487,19 @@ export class BrokerTradingController {
         && (request.action === "SELL" ? request.stopPrice >= touch : request.stopPrice <= touch)) {
         warnings.push(request.action === "SELL" ? "This sell stop is at or above the bid, so it triggers at once." : "This buy stop is at or below the ask, so it triggers at once.");
       }
+      // An exit already through the market trades the moment it works: an OCO's at once, a bracket's once the entry fills.
+      // A bracket's exits trade the other way from its entry; an OCO's two orders trade its own way. An entry resting away
+      // from the market fills at its own price, and its exits were checked against that: only one that trades now, at
+      // the market, can leave an exit through it.
+      const exitSells = request.orderClass === "oco" ? request.action === "SELL" : request.action === "BUY";
+      const exitTouch = request.orderClass === "bracket" && restingEntryPrice(request, quote.quote) !== undefined ? undefined
+        : exitSells ? quote.quote.bid : quote.quote.ask;
+      if (request.orderClass && positive(exitTouch) && positive(request.stopLossPrice) && (exitSells ? request.stopLossPrice >= exitTouch : request.stopLossPrice <= exitTouch)) {
+        warnings.push(request.orderClass === "oco" ? `This ${exitSells ? "sell" : "buy"} stop is through the market, so it triggers at once.` : "The stop loss is through the market, so it triggers as soon as the entry fills.");
+      }
+      if (request.orderClass === "bracket" && positive(exitTouch) && positive(request.takeProfitPrice) && (exitSells ? request.takeProfitPrice <= exitTouch : request.takeProfitPrice >= exitTouch)) {
+        warnings.push("The take profit is through the market, so it fills as soon as the entry does.");
+      }
       if (quote.quote.marketState === "CLOSED") warnings.push("The broker reports the market is closed. The order may wait for another session.");
       // Legs whose quotes net the other way: a debit order that would be paid, or a credit order that would pay.
       if (request.legs?.length && Number.isFinite(quote.quote.price) && quote.quote.price <= 0) warnings.push(request.action === "BUY"
@@ -482,7 +509,7 @@ export class BrokerTradingController {
       const result: BrokerOrderReview = { request, preview: copy(preview), warnings: [...new Set(warnings)], account: copy(account), brokerName: context.adapter.name,
         createdAt: this.now(), mode: this.modifyOrder ? "modify" : "place", requiresTypedConfirmation: account.tradingMode !== "simulation", confirmationText: request.contract.symbol.toUpperCase() };
       this.gate = { context: fingerprint, request: canonical(request), version, quoteRisk: this.quoteRisk(quote), order: this.modifyOrder ? copy(this.modifyOrder) : undefined };
-      this.publish({ phase: skipConfirmation && !result.warnings.length && !preview.errors?.length ? "previewing" : "review", review: result, quote, error: preview.errors?.length ? "The broker preview has blocking errors." : undefined });
+      this.publish({ phase: skipConfirmation && !result.warnings.length && !preview.errors?.length && !asksForConsent(preview) ? "previewing" : "review", review: result, quote, error: preview.errors?.length ? "The broker preview has blocking errors." : undefined });
     } catch (error) {
       if (!this.disposed && version === this.version) this.publish({ phase: "editing", review: undefined, error: errorMessage(error, "The broker could not preview this order.") });
       throw error;
@@ -537,7 +564,7 @@ export class BrokerTradingController {
     const { context, capabilities } = this.context(true, request);
     this.checkOrder(order, context, "modify");
     if (!capabilities.modify || !context.adapter.modifyOrder) throw new Error("This broker does not support modifying this order.");
-    if (!["MKT", "LMT", "STP", "STP LMT"].includes(order.orderType)) throw new Error("This order type cannot be modified in the shared ticket.");
+    if (!["MKT", "LMT", "STP", "STP LMT", "TRAIL"].includes(order.orderType)) throw new Error("This order type cannot be modified in the shared ticket.");
     this.modifyOrder = undefined;
     this.setDraft({ ...request, brokerInstanceId: context.instance.id });
     this.modifyOrder = copy(order);
@@ -561,7 +588,10 @@ export class BrokerTradingController {
 
   private orderRequest(order: BrokerOrder): BrokerOrderRequest {
     return { brokerInstanceId: order.brokerInstanceId, accountId: order.accountId, contract: copy(order.contract), action: order.action,
-      orderType: order.orderType as BrokerOrderRequest["orderType"], quantity: order.quantity, limitPrice: order.limitPrice, stopPrice: order.stopPrice, tif: order.tif,
+      orderType: order.orderType as BrokerOrderRequest["orderType"], quantity: order.quantity, tif: order.tif,
+      // A trailing stop's trigger is the broker's to move: a change sets its distance.
+      ...(order.orderType === "TRAIL" ? order.trailingPercent !== undefined ? { trailingPercent: order.trailingPercent } : { trailingAmount: order.trailingAmount }
+        : { limitPrice: order.limitPrice, stopPrice: order.stopPrice }),
       ...(order.legs?.length ? { legs: copy(order.legs) } : {}) };
   }
 
@@ -608,7 +638,10 @@ export class BrokerTradingController {
         : await context.adapter.listOpenOrders?.(context.instance) ?? [];
       return orders.find((value): value is BrokerOrder => !!value && value.accountId === order.accountId
         && value.contract.symbol === order.contract.symbol && (value.orderId === order.orderId || sameOrder(value, order)));
-    } catch { return undefined; }
+    } catch (error) {
+      logFailure("broker-trading.controller", "Look up broker order failed")(error);
+      throw new Error(orderReadFailed);
+    }
   }
 
   /**
@@ -619,7 +652,10 @@ export class BrokerTradingController {
    */
   private async settleRefusal(order: BrokerOrder, reason: string, action: "modify" | "cancel"): Promise<void> {
     const brokerName = this.context(false).context.adapter.name;
-    const current = await this.lookup(order);
+    let current: BrokerOrder | undefined;
+    let readFailed = false;
+    try { current = await this.lookup(order); }
+    catch { readFailed = true; reason = `${reason}. ${orderReadFailed}`; }
     if (this.disposed) return;
     const now = current ?? order;
     const label = brokerOrderStatus(now.status);
@@ -630,7 +666,7 @@ export class BrokerTradingController {
       this.publish({ phase: "editing", review: undefined, receipt: undefined, error: reason });
       return;
     }
-    this.publish({ phase: "result", cancelOrder: undefined, review: undefined, result: copy(now), resultQuantities: current ? "confirmed" : "last-known", error: undefined });
+    this.publish({ phase: "result", cancelOrder: undefined, review: undefined, result: copy(now), resultQuantities: current ? "confirmed" : "last-known", error: readFailed ? reason : undefined });
     const title = ended ? label === "Rejected" ? reason : `Already ${label.toLowerCase()}` : changed ? `Order changed in ${brokerName}, refreshed` : reason;
     this.options.onOutcome?.({ title, type: ended || changed ? "info" : "error", order: copy(now) });
   }
@@ -645,16 +681,22 @@ export class BrokerTradingController {
   async refreshResult(): Promise<void> {
     const result = this.snapshot.result;
     if (!result) return;
-    const { context } = this.context(false);
-    if (!context.adapter.listOpenOrders && !context.adapter.getOrderStatus) throw new Error("Refresh this order in your broker.");
     const fingerprint = this.key();
-    const orders = context.adapter.getOrderStatus && result.orderId !== 0
-      ? [await context.adapter.getOrderStatus(context.instance, result.orderId)].filter((order): order is BrokerOrder => order !== null)
-      : await context.adapter.listOpenOrders?.(context.instance) ?? [];
-    if (this.disposed || fingerprint !== this.key() || this.snapshot.result !== result) return;
-    const current = orders.find((order) => order.accountId === result.accountId && order.contract.symbol === result.contract.symbol && sameOrder(order, result));
-    if (current) this.publish({ result: copy(current), resultQuantities: "confirmed", error: current.status === "UNKNOWN" ? uncertainChange : undefined });
-    // Absence from open orders does not prove a fill, rejection or cancellation.
+    const stillCurrent = () => !this.disposed && fingerprint === this.key() && this.snapshot.result === result;
+    try {
+      const { context } = this.context(false);
+      if (!context.adapter.listOpenOrders && !context.adapter.getOrderStatus) throw new Error("Refresh this order in your broker.");
+      const orders = context.adapter.getOrderStatus && result.orderId !== 0
+        ? [await context.adapter.getOrderStatus(context.instance, result.orderId)].filter((order): order is BrokerOrder => order !== null)
+        : await context.adapter.listOpenOrders?.(context.instance) ?? [];
+      if (!stillCurrent()) return;
+      const current = orders.find((order) => order.accountId === result.accountId && order.contract.symbol === result.contract.symbol && sameOrder(order, result));
+      if (current) this.publish({ result: copy(current), resultQuantities: "confirmed", error: current.status === "UNKNOWN" ? uncertainChange : undefined });
+      // Absence from open orders does not prove a fill, rejection or cancellation, or clear a read failure.
+    } catch {
+      if (stillCurrent()) this.publish({ error: orderReadFailed, resultQuantities: this.snapshot.resultQuantities === "unconfirmed" ? "unconfirmed" : "last-known" });
+      throw new Error(orderReadFailed);
+    }
   }
 
   /**

package/src/plugins/builtin/broker-trading/dock.tsx

@@ -1,4 +1,4 @@
-import { startTransition, useCallback, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { startTransition, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import { PaneFooterScope, usePaneMenuItems } from "../../../components";
 import { usePaneAppConfig, usePaneStateValue } from "../../../state/app/context";
 import { usePluginBrokerActions } from "../../runtime";
@@ -91,15 +91,33 @@ export function ResearchTradeWorkspace({ width, height, focused, symbol, tabId,
   const ticketFocused = split && panelFocused;
   // The chart consumes its own presses, so the box below never hears them: it says so itself.
   const focusChart = useCallback(() => setPanelFocused(false), []);
-  const context = useMemo(() => ({ ...projection, symbol, available, docked, visible, ticketFocused, open: openTicket, close, focusChart, publish, ...(available ? { orders } : {}) }),
-    [projection, symbol, available, docked, visible, ticketFocused, openTicket, close, focusChart, orders]);
+  // A price picked on the chart beside the ticket: the chart takes the keys until it is picked or cancelled.
+  const [pickingField, setPickingField] = useState<string>();
+  const picking = split ? projection.priceFields?.find((entry) => entry.field === pickingField) : undefined;
+  const pickPrice = useCallback((field?: string) => {
+    const choice = field ? projection.priceFields?.find((entry) => entry.field === field) : projection.priceFields?.[0];
+    if (!split || !choice) return;
+    captureTicket(false); setPickingField(choice.field); setPanelFocused(false);
+  }, [split, projection.priceFields, captureTicket]);
+  const cancelPick = useCallback(() => { setPickingField(undefined); setPanelFocused(true); }, []);
+  const finishPick = useCallback((value: number) => {
+    if (picking) projection.setPrice?.(picking.field, value);
+    cancelPick();
+  }, [picking, projection, cancelPick]);
+  // Back in the ticket, away from the pane, or a ticket that no longer has that price: the pick is over.
+  useEffect(() => { if (pickingField && (!focused || ticketFocused || !picking)) setPickingField(undefined); }, [pickingField, focused, ticketFocused, picking]);
+  const context = useMemo(() => ({ ...projection, symbol, available, docked, visible, ticketFocused, open: openTicket, close, focusChart, publish,
+    picking, pickPrice, finishPick, cancelPick, ...(available ? { orders } : {}) }),
+  [projection, symbol, available, docked, visible, ticketFocused, openTicket, close, focusChart, orders, picking, pickPrice, finishPick, cancelPick]);
   useShortcut((event) => {
     if (event.name !== "f6" || event.repeat) return;
     event.preventDefault(); event.stopPropagation(); captureTicket(false); setPanelFocused((value) => !value);
   }, { enabled: focused && split && !dialogOpen, allowEditable: true, phase: "before", scope: "research:trade-focus" });
   useShortcut((event) => {
     if (event.name !== "escape" || event.defaultPrevented || event.targetEditable) return;
-    event.preventDefault(); event.stopPropagation(); close();
+    event.preventDefault(); event.stopPropagation();
+    // While the chart picks a price, Esc only ends the pick, here too when the chart has nothing drawn to take it.
+    if (pickingField) cancelPick(); else close();
   }, { enabled: focused && split && !panelFocused && !dialogOpen, phase: "after", scope: "research:trade-close" });
 
   // The divider between chart and ticket drags, and < > move it from the keyboard.

package/src/plugins/builtin/broker-trading/headless.ts

@@ -1,6 +1,7 @@
 import type { BrokerAdapter } from "../../../types/broker";
 import type { HeadlessPaneContext, HeadlessPaneDefinition, HeadlessPaneColumn } from "../../../types/headless";
 import { brokerOrderStatus, loadBrokerOrdersSnapshot } from "./orders-data";
+import { accountsShownFor } from "../../../brokers/broker-portfolio-sync";
 
 type BrokerResolver = (brokerType: string, context: HeadlessPaneContext) => BrokerAdapter | null;
 
@@ -44,7 +45,7 @@ function createBrokerOrdersHeadless(
       if (!profiles.length) throw new Error("Connect a broker profile that reports orders in Brokers first.");
       const { instance, broker } = profiles[ordinal(args.options.profile, profiles.length, "profile")]!;
       if (!broker.listAccounts) throw new Error("This broker does not report account identities.");
-      const accounts = await broker.listAccounts(instance);
+      const accounts = accountsShownFor(context.config, instance, await broker.listAccounts(instance));
       context.signal.throwIfAborted();
       if (!accounts.length) throw new Error("This broker profile has no available accounts.");
       const account = accounts[ordinal(args.options.account, accounts.length, "account")]!;

package/src/plugins/builtin/broker-trading/index.tsx

@@ -5,7 +5,11 @@ import { brokerCanTrade, createTradeCommand, openTradeTicket } from "./command";
 import { brokerOrderFeed } from "./order-feed";
 import { tickerSecType } from "./pane-model";
 
-/** Every enabled trading profile's orders, held for as long as the app runs: its fills toast with no ticket open. */
+/**
+ * Every enabled trading profile's orders, held for as long as the app runs:
+ * its fills toast with no ticket open, and sync the profile's positions into
+ * its portfolio.
+ */
 let releaseHeldOrders: (() => void) | undefined;
 
 /** A ticker without a saved asset category trades as its research instrument kind says. */
@@ -28,6 +32,19 @@ export const brokerTradingModule: PluginModule = {
   }],
   setup(ctx) {
     brokerOrderFeed.setNotifier((notification) => { ctx.notify(notification); });
+    brokerOrderFeed.setPositionSync(async (instanceId) => {
+      try {
+        await ctx.syncBrokerInstance(instanceId);
+      } catch (error) {
+        ctx.notify({
+          title: "Position sync failed",
+          body: "The fill was received, but positions could not be synced. Use Sync in Brokers to retry.",
+          type: "error",
+          action: { label: "Brokers", onClick: () => ctx.showPane("brokers") },
+        });
+        throw error;
+      }
+    });
     let held = new Map<string, { key: string; release(): void }>();
     // A broker registered by a later plugin, or a profile added or edited, is held from then on.
     const holdProfiles = () => {
@@ -50,6 +67,7 @@ export const brokerTradingModule: PluginModule = {
       for (const entry of held.values()) entry.release();
       held.clear();
       brokerOrderFeed.setNotifier(undefined);
+      brokerOrderFeed.setPositionSync(undefined);
       brokerOrderFeed.clear();
     };
     const supported = (symbol: string, secType = "STK") => brokerCanTrade(ctx.getConfig().brokerInstances, (type) => ctx.getBrokerAdapter?.(type), symbol, secType);

package/src/plugins/builtin/broker-trading/linked-orders.ts

@@ -0,0 +1,148 @@
+import type { Quote } from "../../../types/financials";
+import type { BrokerOrder, BrokerOrderClass, BrokerOrderLinkRole, BrokerOrderRequest, BrokerTradingCapabilities, BrokerTrailingUnit } from "../../../types/trading";
+
+/**
+ * Brackets, OCO pairs and trailing stops: what a broker takes, what a draft of
+ * one must hold, and how the orders it becomes are listed together. The broker
+ * places and runs them; nothing here makes one out of separate orders.
+ */
+
+export type LinkedFeature = BrokerOrderClass | "trailing";
+
+const FEATURE_NAME: Record<LinkedFeature, string> = { bracket: "brackets", oco: "OCO orders", trailing: "trailing stops" };
+
+/** Whether the broker takes a bracket, an OCO pair or a trailing stop here, and the refusal when it does not. */
+export function linkedFeature(capabilities: BrokerTradingCapabilities | undefined, feature: LinkedFeature, brokerName: string): { available: boolean; reason?: string } {
+  const available = feature === "trailing"
+    ? !!capabilities?.orderTypes.includes("TRAIL") && !!capabilities.trailing?.length
+    : !!capabilities?.orderClasses?.includes(feature);
+  if (available) return { available };
+  return { available, reason: `${brokerName} does not take ${FEATURE_NAME[feature]}.` };
+}
+
+/** The trailing unit a draft edits: percent once it holds one, else the amount. */
+export function trailingUnit(request: Pick<BrokerOrderRequest, "trailingAmount" | "trailingPercent">): BrokerTrailingUnit {
+  return "trailingPercent" in request && !("trailingAmount" in request) ? "percent" : "amount";
+}
+
+const positive = (value: number | undefined): value is number => value !== undefined && Number.isFinite(value) && value > 0;
+
+/**
+ * The entry's own price an exit is measured against: its limit, or its stop,
+ * or none for a market order.
+ */
+function entryPrice(request: BrokerOrderRequest): number | undefined {
+  if (request.orderType === "LMT" || request.orderType === "STP LMT") return request.limitPrice;
+  if (request.orderType === "STP") return request.stopPrice;
+  return undefined;
+}
+
+/**
+ * The entry's price when it rests away from the market, where it fills: a buy
+ * limit under the ask or a buy stop over it, a sell the mirror. None for one
+ * that trades now, or without a quote.
+ */
+export function restingEntryPrice(request: BrokerOrderRequest, quote: Pick<Quote, "bid" | "ask">): number | undefined {
+  const buy = request.action === "BUY";
+  const touch = buy ? quote.ask : quote.bid;
+  if (!positive(touch)) return undefined;
+  const entry = entryPrice(request);
+  if (request.orderType === "LMT") return positive(entry) && (buy ? entry < touch : entry > touch) ? entry : undefined;
+  if (request.orderType === "STP" || request.orderType === "STP LMT") {
+    return positive(request.stopPrice) && (buy ? request.stopPrice > touch : request.stopPrice < touch) ? entry : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Checks a draft's bracket, OCO pair or trailing stop against what the broker
+ * declared, before any preview. Throws with the reason to show.
+ */
+export function checkLinkedOrder(request: BrokerOrderRequest, capabilities: BrokerTradingCapabilities, brokerName: string, checkPrice: (value: number, label: string) => void): void {
+  const buy = request.action === "BUY";
+  const trailing = request.orderType === "TRAIL";
+  if (!trailing && (request.trailingAmount !== undefined || request.trailingPercent !== undefined)) throw new Error("Remove the trailing distance for this order type.");
+  if (trailing) {
+    const feature = linkedFeature(capabilities, "trailing", brokerName);
+    if (!feature.available) throw new Error(feature.reason);
+    const unit = trailingUnit(request);
+    if ((request.trailingAmount !== undefined) === (request.trailingPercent !== undefined)) throw new Error("Enter the trailing distance in price or in percent.");
+    if (!capabilities.trailing?.includes(unit)) throw new Error(unit === "percent" ? `${brokerName} takes a trailing stop in price, not percent.` : `${brokerName} takes a trailing stop in percent, not price.`);
+    const distance = unit === "percent" ? request.trailingPercent : request.trailingAmount;
+    if (!positive(distance) || unit === "percent" && distance >= 100) throw new Error("Enter a valid trailing distance.");
+    if (unit === "amount") checkPrice(distance, "trailing");
+  }
+  const exits = request.takeProfitPrice !== undefined || request.stopLossPrice !== undefined;
+  if (!request.orderClass) {
+    if (exits) throw new Error("Remove the take profit and stop loss, or make the order a bracket.");
+    return;
+  }
+  const feature = linkedFeature(capabilities, request.orderClass, brokerName);
+  if (!feature.available) throw new Error(feature.reason);
+  if (request.legs?.length) throw new Error("A spread cannot carry a bracket or an OCO pair.");
+  if (request.orderClass === "oco") {
+    if (request.orderType !== "LMT") throw new Error("An OCO pair is a limit and a stop.");
+    if (request.takeProfitPrice !== undefined) throw new Error("An OCO pair is a limit and a stop, with no take profit.");
+    if (!positive(request.stopLossPrice)) throw new Error("Enter a valid stop price.");
+    checkPrice(request.stopLossPrice, "stop");
+    // A sell pair exits a long: a limit above, a stop below. A buy pair is the mirror.
+    if (positive(request.limitPrice) && (buy ? request.limitPrice >= request.stopLossPrice : request.limitPrice <= request.stopLossPrice)) {
+      throw new Error(buy ? "A buy OCO's limit sits below its stop." : "A sell OCO's limit sits above its stop.");
+    }
+    return;
+  }
+  if (!["MKT", "LMT", "STP", "STP LMT"].includes(request.orderType)) throw new Error("A bracket's entry is a market, limit or stop order.");
+  if (!positive(request.takeProfitPrice) && !positive(request.stopLossPrice)) throw new Error("Enter a take profit, a stop loss or both.");
+  for (const [value, label] of [[request.takeProfitPrice, "take profit"], [request.stopLossPrice, "stop loss"]] as const) {
+    if (value === undefined) continue;
+    if (!positive(value)) throw new Error(`Enter a valid ${label} price.`);
+    checkPrice(value, label);
+  }
+  // A buy's take profit sells above where it bought and its stop loss below; a sell's the mirror.
+  const entry = entryPrice(request);
+  const above = (value: number, than: number) => buy ? value > than : value < than;
+  if (positive(entry) && positive(request.takeProfitPrice) && !above(request.takeProfitPrice, entry)) throw new Error(buy ? "The take profit must be above the entry." : "The take profit must be below the entry.");
+  if (positive(entry) && positive(request.stopLossPrice) && !above(entry, request.stopLossPrice)) throw new Error(buy ? "The stop loss must be below the entry." : "The stop loss must be above the entry.");
+  if (positive(request.takeProfitPrice) && positive(request.stopLossPrice) && !above(request.takeProfitPrice, request.stopLossPrice)) {
+    throw new Error(buy ? "The take profit must be above the stop loss." : "The take profit must be below the stop loss.");
+  }
+}
+
+export const linkRoleName: Record<BrokerOrderLinkRole, string> = { entry: "Entry", takeProfit: "Take profit", stopLoss: "Stop loss" };
+/** Beside a price in a one-line row. */
+export const linkRoleShort: Record<BrokerOrderLinkRole, string> = { entry: "", takeProfit: "TP", stopLoss: "SL" };
+
+/** "Trailing $1.50", "Trailing 2%": a trailing stop's distance. */
+export function trailingText(order: Pick<BrokerOrder, "trailingAmount" | "trailingPercent">, money: (value: number) => string): string {
+  if (positive(order.trailingPercent)) return `Trailing ${order.trailingPercent.toLocaleString("en-US", { maximumFractionDigits: 4 })}%`;
+  return positive(order.trailingAmount) ? `Trailing ${money(order.trailingAmount)}` : "Trailing";
+}
+
+const ROLE_ORDER: Record<BrokerOrderLinkRole, number> = { entry: 0, takeProfit: 1, stopLoss: 2 };
+
+/**
+ * Orders as a list shows them: newest first, with each group's orders
+ * together where its newest one sits, the entry before its take profit and
+ * stop loss. `child` marks an exit listed under its entry.
+ */
+export function linkedOrderRows<T extends Pick<BrokerOrder, "linkGroup" | "linkRole" | "accountId">>(orders: readonly T[]): Array<{ order: T; child: boolean }> {
+  const groups = new Map<string, T[]>();
+  for (const order of orders) {
+    if (!order.linkGroup) continue;
+    const key = `${order.accountId ?? ""}:${order.linkGroup}`;
+    groups.set(key, [...groups.get(key) ?? [], order]);
+  }
+  const rows: Array<{ order: T; child: boolean }> = [];
+  const placed = new Set<string>();
+  for (const order of orders) {
+    const key = order.linkGroup ? `${order.accountId ?? ""}:${order.linkGroup}` : undefined;
+    const group = key ? groups.get(key) : undefined;
+    if (!key || !group || group.length < 2) { rows.push({ order, child: false }); continue; }
+    if (placed.has(key)) continue;
+    placed.add(key);
+    const sorted = [...group].sort((a, b) => ROLE_ORDER[a.linkRole ?? "entry"] - ROLE_ORDER[b.linkRole ?? "entry"]);
+    const entry = sorted.some((item) => item.linkRole === "entry");
+    for (const item of sorted) rows.push({ order: item, child: entry && item.linkRole !== "entry" });
+  }
+  return rows;
+}