openpinescript 0.0.0-stage → 0.1.1

package/dist/types/runtime/v1/broker/Broker.d.ts

@@ -0,0 +1,325 @@
+/**
+ * The broker for Pine v1 to v5. TradingView's migration guides list no strategy
+ * or broker change between those versions: to-pine-version-3 and -4 have none,
+ * and to-pine-version-5 lists compile-time checks only (https://www.tradingview.com/pine-script-docs/migration-guides/to-pine-version-3/,
+ * .../to-pine-version-4/, .../to-pine-version-5/). It holds every rule
+ * TradingView's own logs have shown, and V6Broker extends it, overriding only
+ * what the v6 guide documents (https://www.tradingview.com/pine-script-docs/migration-guides/to-pine-version-6/).
+ *
+ *   rule                                                    v1–v5            v6               status
+ *   per-entry closed trades, first in first out             yes              yes (same)       log-verified (pyr0, pyr3: v5 and v6 identical)
+ *   strategy.close(id) takes its qty off the position FIFO  yes              yes (same)       log-verified (pyr3 phase d)
+ *   an opposite strategy.order closes the oldest entry      yes              yes (same)       log-verified (pyr0 phase c)
+ *   process_orders_on_close fills at the placing bar close  yes              yes (same)       log-verified (pooc)
+ *   close(immediately) fills at the bar close, after script yes              yes (same)       log-verified (pyr0 g2, g4)
+ *   strategy.exit once per entry, qty_percent of opened     yes              yes (same)       log-verified (v5 release_notes_04, v6 golden)
+ *   two ledgers: an id's quantity apart from the trades    yes              yes (same)       log-verified (exit_mix a; pyr3 d). from_entry / close(id) draw on the id, the fill takes the OLDEST trades
+ *   relative exit levels from each trade's own fill price   yes              yes (same)       log-verified (exit_mix a, e; reentry b: two L fills, each its own target)
+ *   an exit with no from_entry is one order per entry id    yes              yes (same)       log-verified (exit_mix c, d). Each id has its own qty and its own trail
+ *   one exit unit per trade, re-armed when the id re-enters yes              yes (same)       log-verified (reentry a, 5m and 1D: xa fills again for the second A)
+ *   a bar's exits fill in price-path order, oldest trade    yes              yes (same)       log-verified (reentry c1-c4: limit first when the open is nearer the high, stop first when nearer the low)
+ *   exit() before its entry exists has no effect that call  yes              yes (same)       log-verified (exit_order d1/d2 on AAPL 5m; reentry a; release_notes_04)
+ *   trailing stop with offset 0 holds at its activation    yes              yes (same)       log-verified (v5 and v6 release_notes_04: fills at 4285.58, 4286.08); a nonzero offset follows intrabar (v6 harness_v6_strategy), the same rule for all
+ *   margin_long / margin_short                              0, no checks     100, entries blocked, shorts called   log-verified for the block (v6 release_notes_04 at 100K capital); margin calls doc-only (MG "Default margin percentage")
+ *   strategy.exit absolute vs relative pairs                absolute wins    nearer level wins     doc-only (MG "strategy.exit() evaluates parameter pairs")
+ *   9000 orders                                             runtime error    oldest trimmed   doc-only (MG "Excess orders are trimmed")
+ *   `when` argument                                         accepted         compile error    doc-only (MG "Removal of when parameter")
+ *   calc_bars_count (security, security_lower_tf)           no effect        no effect        log-verified (harness_security_cbc, v5): accepted, never limits history
+ *   entry commission charged at the fill                    yes              yes (same)       log-verified on v6 (harness_v6_strategy), applied to all: the guides document no difference
+ */
+/**
+ * runtime/v1/broker/Broker.ts
+ *
+ * The broker emulator, as a class so a Pine version can extend it.
+ *
+ * ── Why a class, when four versions needed no such thing ──────────────────
+ *
+ * TradingView did not change the broker across v1-v5. The v2->v3, v3->v4 and
+ * v4->v5 migration guides document no change to order fills, trade
+ * calculation or the emulator: every strategy delta in them is compile-time
+ * API shape (`strategy.exit()` must have an effect, named constants
+ * mandatory, `long` renamed to `direction`) or a general language rule, and
+ * each is already handled in the transpiler or the registry.
+ *
+ * v6 is the first version where the EMULATOR itself differs. `strategy.exit()`
+ * now evaluates its relative and absolute parameters as a pair and takes
+ * whichever level is expected to trigger first, where v5 always took the
+ * absolute one; and the 9000-order cap trims the oldest orders instead of
+ * halting the script. The same orders produce different fills depending on the
+ * `//@version` line, which is what a subclass is for.
+ *
+ * ── State stays on the Context, and that is deliberate ────────────────────
+ *
+ * `Context` snapshots broker state for live-tick re-evaluation and restores it
+ * with `structuredClone` (`RuntimeSnapshot`, ../context.ts). `structuredClone`
+ * does not preserve prototypes: cloning an instance would return a plain
+ * object with no methods, and the next call on the restored broker would throw
+ * — on the live path, which the ordinary suite does not exercise on every run.
+ *
+ * So this class is BEHAVIOUR and the context keeps the DATA. The accessors
+ * below still read `(ctx as any)._pendingExits` and friends, which is exactly
+ * what the snapshot already clones by name.
+ */
+import type { Context } from "../context.js";
+import { type PendingExit, type ExitUnit, type PendingEntry, type RiskState, type MarketOrder } from "../stdlib/strategy.js";
+export declare class Broker {
+    protected readonly ctx: Context;
+    constructor(ctx: Context);
+    protected getPendingExits(): Map<string, PendingExit>;
+    protected getPendingEntries(): Map<string, PendingEntry>;
+    getRiskState(): RiskState;
+    protected syncRiskState(): RiskState;
+    /**
+     * The equity `strategy.risk.max_drawdown` measures: open equity before v5, where nothing
+     * contradicts it (see V5Broker for what TradingView does).
+     */
+    protected drawdownEquity(): number;
+    protected checkRiskHalt(rs: RiskState): boolean;
+    protected gated(when: any): boolean;
+    order(id: string, dir: string, qty?: any, limit?: any, stop?: any, oca_name?: string, oca_type?: string, comment?: string, when?: any, alert_message?: string, obeysPyramiding?: boolean): void;
+    /**
+     * Fills the queued market orders at `price`: the open of the bar after the
+     * one that placed them, or with `process_orders_on_close` the close of the
+     * bar that did (see `Context.finalizeBar`).
+     */
+    fillMarketOrders(price?: number): void;
+    /** Fills a queued `strategy.close` / `close_all` at `price`. */
+    protected fillClose(o: MarketOrder, price: number): void;
+    entry(id: string, direction: string, qty?: any, limit?: any, stop?: any, oca_name?: string, oca_type?: string, comment?: string, when?: any, alert_message?: string, overridePrice?: number, viaLimit?: boolean, exempt?: boolean, sizingPrice?: number): boolean;
+    /**
+     * Whether `pyramiding` holds back an entry in this direction: the position
+     * is already open the same way with as many entries as it allows.
+     */
+    protected pyramidingBlocks(isLong: boolean, exempt: boolean): boolean;
+    /**
+     * Whether a cash / percent-of-equity size is computed at the price the ORDER names rather
+     * than the price it fills at: a market entry at the close of the bar that placed it, a
+     * limit entry at its limit price even when it fills at a better open. TradingView v6,
+     * AAPL 1D: dev-docs/tv-parity/_probes/sizing-price/run-20261113-043958 (market ps = qc,
+     * floor(eq/close[1]); limit ps = ql, floor(eq/limit)). Only v6 has the evidence; V6Broker
+     * turns it on, and moving the override to V5Broker (or here) widens it.
+     */
+    protected sizesAtOrderPrice(): boolean;
+    /** `orderPrice` when sizing follows the order's price, else undefined (size at the fill price). */
+    protected sizingPriceFor(orderPrice: number | undefined): number | undefined;
+    /** The quantity an entry with no `qty` takes at `price`: `strategy.default_entry_qty`. */
+    entryQtyAt(price: number): number;
+    /**
+     * TradingView floors an order's quantity to `syminfo.mincontract`, the
+     * script's own variable staying as written. Only when the host supplied
+     * the minimum: the context default (1) would floor fractional sizes to 0.
+     */
+    /**
+     * Whether quantities are floored to `syminfo.mincontract`. TradingView evidence: v4
+     * (Adaptive Momentum Test, floor to 0.00001), v5 (_probes/v5-sizing) and v6 (_probes/sizing). Overridden in
+     * V4Broker (v5, v6 inherit); v2 and v3 were not probed and keep the unfloored size.
+     */
+    protected floorsToMinContract(): boolean;
+    /**
+     * Whether a percent_of_equity size leaves room for the entry commission:
+     * `equity * pct / (price * (1 + commission%))`. Evidence: v4 (_probes/version-scope/v4-sizing,
+     * 30/30 trades), v5 (_probes/v5-sizing) and v6 (_probes/sizing). Overridden in V4Broker (v5, v6 inherit).
+     */
+    protected sizesWithCommissionRoom(): boolean;
+    /**
+     * Whether each fill's commission is rounded to 8 decimals. Evidence: v6 only
+     * (_probes/sizing-precision); v4-sizing checks position sizes, not commission values.
+     */
+    protected roundsCommissionTo8(): boolean;
+    protected floorToMinContract(qty: number): number;
+    protected defaultQty(price: number): number;
+    close(id: string, when?: any, comment?: string, qty?: any, qty_percent?: any, alert_message?: string, immediately?: any): void;
+    close_all(comment?: string, when?: any, alert_message?: string, immediately?: any): void;
+    /**
+     * Queues a close for the next bar's open -- see MarketOrder -- or, with
+     * `immediately`, fills it now. strategy.close_all: "immediately (series
+     * bool) If true, the closing order will be executed on the tick where it
+     * has been placed, ignoring the strategy parameters that restrict the
+     * order execution to the open of the next bar." On a historical bar the
+     * tick that places it is the bar's close.
+     */
+    protected placeClose(order: MarketOrder, immediately: any): void;
+    closeAt(comment: string, price: number, exitId?: string, exitComment?: string): void;
+    cancel(id: string, when?: any): void;
+    cancel_all(): void;
+    exit(id: string, from_entry?: string, qty?: any, qty_percent?: any, profit?: any, limit?: any, loss?: any, stop?: any, trail_price?: any, trail_points?: any, trail_offset?: any, oca_name?: string, comment?: string, when?: any, alert_message?: string, comment_profit?: string, comment_loss?: string, comment_trailing?: string): void;
+    /**
+     * May an entry of `qty` at `price` be placed? A seam for V6Broker's margin
+     * rule; every version before it admits every entry, as it always has.
+     */
+    protected admitsEntry(_isLong: boolean, _qty: number, _price: number): boolean;
+    /**
+     * `strategy.netprofit`: the closed trades' profit, which already carries
+     * each trade's commission. Summed as the trades close (`recordTrade`), in
+     * the order a re-sum would add them, and rolled back with the snapshot.
+     */
+    netProfit(): number;
+    /**
+     * What `strategy.netprofit` reports: the closed trades' profit less the
+     * open position's entry commission, charged when the entry FILLS, not when
+     * the trade closes. TradingView's v6 log reads -12.0041896 the bar a 0.731
+     * entry at 82108 fills, at 0.02% (conformance/v6/golden/harness_v6_strategy).
+     * The migration guides document no difference between versions, so every
+     * version has it. Only the accessor: `avg_trade` and `netprofit_percent`
+     * are defined over closed trades, and stay on `netProfit`.
+     */
+    reportedNetProfit(): number;
+    /**
+     * The margin requirement for a side, as a ratio: 25% margin is 0.25, and
+     * 0 when the script sets none. Enforced only by V6Broker; read by
+     * `strategy.margin_liquidation_price` too, so the two cannot disagree.
+     */
+    marginRatio(isLong: boolean): number;
+    /**
+     * Fills at the bar's close what is due there once the script has run: every
+     * queued market order under `process_orders_on_close`, otherwise the
+     * closes placed with `immediately`.
+     */
+    fillAtClose(): void;
+    /**
+     * Whether the strategy halts at its 9000th order (v4, v5) instead of
+     * trimming the oldest (v6, which overrides this). Doc-only; see the table at the top of this file.
+     */
+    protected haltsAtOrderLimit(): boolean;
+    /** One more order filled: past 9000 a pre-v6 strategy stops with a runtime error. */
+    protected countOrder(): void;
+    /** Whether market orders fill at the close of the bar that placed them. */
+    fillsOnClose(): boolean;
+    /**
+     * One exit level, given as an absolute PRICE and/or a RELATIVE distance
+     * (already converted to a price). Either may be NaN.
+     *
+     * v1–v5: "When both absolute (limit, stop) and relative (profit, loss)
+     * parameters are given, the absolute ones always win" — the v6 migration
+     * guide, describing v5. `favourable` and `isLong` are unused here; they are
+     * what V6Broker needs to choose between the two instead.
+     */
+    protected pairLevel(absolute: number, relative: number, _isLong: boolean, _favourable: boolean): number;
+    protected applyEntryOCA(entries: Map<string, PendingEntry>, filledOrder: PendingEntry, price: number): void;
+    protected applyExitOCA(exits: Map<string, PendingExit>, filledExit: PendingExit): void;
+    protected commissionFor(price: number, qty: number): number;
+    protected slip(price: number, buying: boolean): number;
+    protected recordTrade(t: {
+        id: string;
+        entryPrice: number;
+        exitPrice: number;
+        qty: number;
+        pnl: number;
+        direction: "long" | "short";
+        exitId?: string;
+        exitComment?: string;
+        /** The entry this trade closes, where the broker tracks entries. */
+        entry?: {
+            id: string;
+            bar: number;
+            time: number;
+            commission: number;
+        };
+        /** A further entry closed by the same order: a flat per-order fee was paid by the first. */
+        sameOrder?: boolean;
+    }): void;
+    protected entryTimeOf(): number;
+    protected toTick(price: number): number;
+    /**
+     * A price already on the tick, with the float noise `round(p / tick) * tick`
+     * leaves (92.85 comes out 92.85000000000001) written off. The entry's own
+     * fill price is what a closed trade reports, so it has to read as the price.
+     */
+    protected exactTick(price: number): number;
+    protected levelToTick(level: number, above: boolean): number;
+    protected fillPrice(level: number, open: number, worseIsHigher: boolean): number;
+    protected livesYet(placedBar: number): boolean;
+    /**
+     * One step of `calc_on_order_fills`: fills the FIRST pending entry or exit
+     * the rest of the bar's path reaches, and moves the cursor there. False
+     * when nothing more is reached. Market orders are not handled here (they
+     * fill at the cursor's price, see `Context.runBarWithFills`).
+     */
+    processIntrabarStep(): boolean;
+    private pickIntrabar;
+    processPendingOrders(high: number, low: number): void;
+    /**
+     * The risk checks that run before any order is matched: true when one of
+     * them halted the strategy (and so ends the bar's order processing).
+     */
+    protected riskGate(rs: any, high: number, low: number): boolean;
+    /** Matches the pending entries and exits against the whole bar. */
+    protected processBarOrders(rs: any, high: number, low: number): void;
+    /** Fills one exit unit at the level `hit` says the bar reached. */
+    protected fillExitHit(rs: any, exits: Map<string, PendingExit>, exitId: string, pendingExit: PendingExit, unit: ExitUnit, hit: {
+        price: number;
+        kind: string;
+    }, isLong: boolean): void;
+    /**
+     * Where the bar first reaches an exit's limit, stop or trailing stop,
+     * walking the bar the way TradingView's broker emulator does: "if the
+     * high is closer to the open than the low, open → high → low → close,
+     * otherwise open → low → high → close". Used where the broker tracks
+     * trades (every version).
+     *
+     * The order matters for a trailing stop more than for anything else. A
+     * bar that opens at its high and falls through the activation level arms
+     * the trail at the LOW; the high came before, so it cannot stop the
+     * position out. Testing the bar's high against a trail armed by its low
+     * exited a short TradingView kept (bar 220 of
+     * conformance/v6/golden/harness_v6_strategy).
+     *
+     * Prices are mirrored for a short, so "up" is always the favourable side:
+     * the limit above, the stops below. The trail's best price is carried
+     * across bars in `trail_peak`, in real prices.
+     *
+     * Performance: `processPendingOrders` calls this once per exit, not once per
+     * unit, for an exit with no relative levels (`profit`, `loss`) and no trail
+     * (`trail_price`, `trail_points`), and gives every unit the one answer. That
+     * holds only while, for such an exit, this reads nothing from `st` or `basis`
+     * and leaves `st.trail_peak` as it found it (it writes back what it read,
+     * NaN or the unit's own peak, which is no change). If this ever reads the
+     * unit or `basis` there, update `levelsFixed` in `processPendingOrders`
+     * together with it. Guarded by tests/v1/runtime/broker_exit_sharing.test.ts.
+     */
+    protected walkExit(ex: PendingExit, st: {
+        trail_peak: number;
+    }, basis: number, isLong: boolean, open: number, high: number, low: number, close: number, path?: number[]): {
+        hit: {
+            price: number;
+            kind: "limit" | "stop" | "trail";
+        } | null;
+        at: number;
+    };
+    /**
+     * Whether the exit already has a unit for trade `uid`. Performance: a scan
+     * from the newest, where the live trade's unit is, instead of
+     * `units.some` over the thousands a reversing strategy leaves behind.
+     */
+    protected hasUnit(units: ExitUnit[], uid: string | undefined): boolean;
+    /**
+     * How much the exit unit `unit` may sell: its trade's share (`qty`, else
+     * `qty_percent` of what the trade opened, else all of it), less what the
+     * unfilled units BEFORE it (exits in placement order, units in trade order)
+     * have reserved on the same entry id, and never more than the id still owns.
+     */
+    protected reservedQty(exits: Map<string, PendingExit>, unit: ExitUnit): number;
+    /** What the entry id still owns on the ledger; see `Position.ledger`. */
+    protected openQty(id: string): number;
+    /**
+     * The price a relative level is measured from for an exit scoped to entry
+     * `id`: the fill price of the oldest open trade with that id
+     * (harness_strategy_exit_mix: `profit = 1` from_entry "B" exits at B's fill
+     * plus one tick, not at the average). Several trades under one id are not
+     * covered by the log; the oldest is a choice. With none open, the average.
+     */
+    protected basisPrice(id: string): number;
+    /**
+     * Closes `qty` of the position at `price` (already on the tick and
+     * slipped), from the entries named `only` or else oldest first, and books
+     * ONE TRADE PER ENTRY it consumes, at that entry's own price and with that
+     * entry's own commission — TradingView's list of trades. What is left
+     * re-averages: the position's price is the remaining entries'.
+     */
+    protected closeEntries(qty: number, price: number, only: string | undefined, names: {
+        id: string;
+        exitId?: string;
+        exitComment?: string;
+        ledger?: string;
+    }): void;
+}

package/dist/types/runtime/v1/broker/index.d.ts

@@ -0,0 +1,158 @@
+/**
+ * runtime/v1/broker/index.ts
+ *
+ * One broker class per Pine version, each extending the one below it — the
+ * same chain the transpilers use (`V2ToJsVisitor extends V1ToJsVisitor`, and
+ * so on) and the same chain the version runtimes express as re-exports.
+ *
+ * ── Why four of these are empty ───────────────────────────────────────────
+ *
+ * Because TradingView changed nothing. The v2→v3, v3→v4 and v4→v5 migration
+ * guides document no change to order fills, trade calculation or the broker
+ * emulator; every strategy delta in them is compile-time API shape or a
+ * general language rule, and all of those are already implemented in the
+ * transpiler and the registry.
+ *
+ * An empty subclass is the same kind of statement `runtime/v3/index.ts` makes
+ * by being one re-export line: it records that the question was asked and the
+ * answer was "nothing", and it gives the next version-specific behaviour an
+ * obvious place to land. Deleting them would save five lines and lose that.
+ */
+import type { Context } from "../context.js";
+import { Broker } from "./Broker.js";
+/**
+ * The documented margin-call size, in contracts, or 0 when no call is due.
+ * Pure, so the Strategies page's worked example can be checked against it
+ * digit for digit. `cash` is Initial Capital + Net Profit; `size` is signed.
+ */
+export declare function marginCallSize(cash: number, size: number, avgPrice: number, price: number, ratio: number, minContract?: number): number;
+/**
+ * v1 to v5 share ONE broker, `Broker`. TradingView's own migration guides list
+ * no fill, trade or emulator change between them:
+ *   - https://www.tradingview.com/pine-script-docs/migration-guides/to-pine-version-3/
+ *     no strategy or broker changes (the `security` lookahead default flips,
+ *     which is profile data);
+ *   - https://www.tradingview.com/pine-script-docs/migration-guides/to-pine-version-4/
+ *     renamed built-ins and `na` typing only;
+ *   - https://www.tradingview.com/pine-script-docs/migration-guides/to-pine-version-5/
+ *     compile-time checks only: a `strategy.exit()` must use profit, limit,
+ *     loss, stop or a trail pair; `strategy.long` cannot be passed to `when`;
+ *     `long` became `direction`.
+ * So these classes are empty on purpose: they record that the question was
+ * asked and the answer was "nothing", and give a version-specific difference an
+ * obvious place to land.
+ */
+export declare class V2Broker extends Broker {
+}
+export declare class V3Broker extends V2Broker {
+}
+export declare class V4Broker extends V3Broker {
+    protected floorsToMinContract(): boolean;
+    protected sizesWithCommissionRoom(): boolean;
+}
+export declare class V5Broker extends V4Broker {
+    /**
+     * `strategy.risk.max_drawdown` on TradingView (v5, BINANCE:BTCUSDT 1h; dev-docs/tv-parity/
+     * _probes/risk-drawdown/run-20261113-044227): the drawdown is measured on REALIZED equity
+     * (cash: initial capital plus closed trades), not open equity.
+     * A long held through a 3.1% open-equity drawdown (bar close 2026-01-18 23:00) was not closed
+     * until its scheduled exit, and after the closed-trade drawdown passed 3% (trade 44) the
+     * strategy never traded again. v6 inherits it (its broker takes v5's rules); no v1-v4 evidence.
+     */
+    protected drawdownEquity(): number;
+}
+/**
+ * v6 — the first version whose broker differs.
+ *
+ * MG §"strategy.exit() evaluates parameter pairs": "When both absolute (limit,
+ * stop) and relative (profit, loss) parameters are given, the absolute ones
+ * always win" in v5; in v6 "both levels are evaluated, and the one the price
+ * hits first is used". Price reaches whichever level is NEARER the entry first,
+ * so that is the one kept:
+ *
+ *                     long          short
+ *     take-profit     lower         higher       (favourable side)
+ *     stop-loss       higher        lower        (adverse side)
+ *     trail start     lower         higher       (favourable side)
+ *
+ * The guide's own example is the sharpest check: `profit = 0, loss = 0`
+ * beside 2×ATR `limit`/`stop` exits immediately at the entry price in v6,
+ * because a zero distance is nearer than any ATR.
+ *
+ * It also enforces MARGIN, which no earlier broker does — see the section
+ * below.
+ *
+ * The guide's remaining strategy change, trimming beyond 9000 trades, is NOT
+ * here: it changes what the per-trade accessors report, not what the broker
+ * does, so it is profile data read by runtime/v1/stdlib/trades.ts.
+ */
+export declare class V6Broker extends V5Broker {
+    /**
+     * v6's pyr0, pyr3 and pooc logs are row for row those of v5, so it takes
+     * the same rules. Only the trailing stop differs: v6's own golden
+     * (harness_v6_strategy) has it follow the bar's highs intrabar.
+     */
+    /**
+     * MG §"Excess orders are trimmed": past 9000 orders "v5 raises a runtime
+     * error and halts" and v6 trims the oldest and continues
+     * (https://www.tradingview.com/pine-script-docs/migration-guides/to-pine-version-6/).
+     */
+    protected haltsAtOrderLimit(): boolean;
+    protected floorsToMinContract(): boolean;
+    protected sizesWithCommissionRoom(): boolean;
+    protected roundsCommissionTo8(): boolean;
+    /** Market and limit entries are sized at their order price (see `Broker.sizesAtOrderPrice`). */
+    protected sizesAtOrderPrice(): boolean;
+    /**
+     * "Entries exceeding available funds are blocked." An entry needs
+     * `qty * price * marginRatio` of available funds: equity, less the margin
+     * a same-direction position already ties up. An opposite position is about
+     * to be closed by this entry, so it ties up nothing.
+     */
+    protected admitsEntry(isLong: boolean, qty: number, price: number): boolean;
+    processPendingOrders(high: number, low: number): void;
+    /**
+     * The margin call, transcribed from the Strategies page ("Margin"):
+     *
+     *     Money Spent      = Quantity * Entry Price
+     *     MVS              = Position Size * Current Price
+     *     Open Profit      = MVS - Money Spent            (× -1 if short)
+     *     Equity           = Initial Capital + Net Profit + Open Profit
+     *     Margin           = MVS * Margin Ratio
+     *     Available Funds  = Equity - Margin
+     *     Loss             = Available Funds / Margin Ratio
+     *     Cover Amount     = TRUNCATE(Loss / Current Price)
+     *     Margin Call Size = Cover Amount * 4
+     *
+     * "if a strategy's available funds fall below the required margin" — that
+     * is, Available Funds < 0 — the emulator "immediately liquidates" that size.
+     *
+     * ── Not documented, so chosen and stated ─────────────────────────────
+     *
+     *   Current Price   the bar's ADVERSE extreme — low for a long, high for a
+     *                   short. The page never says which price; this is the
+     *                   rule this engine's own `max_intraday_loss` check uses,
+     *                   and the one that catches a call TradingView's intrabar
+     *                   emulator would also see.
+     *   Fill            at that price, as a market order (so slippage applies),
+     *                   recorded under the id "Margin call".
+
+     * These three want a TradingView-captured fixture before they are trusted
+     * for numbers; the formula itself is the documented one and reproduces the
+     * page's worked example exactly (see tests/v6/runtime/margin.test.ts).
+     */
+    protected checkMarginCall(high: number, low: number): void;
+    /** Closes `qty` of the position at `price`, under the id "Margin call". */
+    protected liquidate(qty: number, price: number): void;
+    protected pairLevel(absolute: number, relative: number, isLong: boolean, favourable: boolean): number;
+}
+export { Broker } from "./Broker.js";
+/**
+ * This context's broker, built once and kept on the context.
+ *
+ * Memoised per context rather than per version, because the instance holds a
+ * reference to its own context. It holds no trading state — that stays on the
+ * context so the live-tick snapshot can keep cloning it (see Broker.ts) — so
+ * rebuilding one would be harmless, just wasteful.
+ */
+export declare function brokerFor(ctx: Context): Broker;

package/dist/types/runtime/v1/broker/val.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Unwraps a Series (or anything with a valueOf) to a primitive number.
+ *
+ * Here rather than in stdlib/strategy.ts, where it used to live as a private
+ * helper: the broker needs it too, and EVERY export of a stdlib module is
+ * published as a Pine built-in by scripts/common/generate-metadata.ts. Exported
+ * from there, it became `strategy.val(x)` — callable from a script.
+ */
+export declare function val(x: any): number;
+/**
+ * Unwraps a Series (or any wrapper with a valueOf) to a primitive string; `na`
+ * is the empty string.
+ *
+ * Every id, comment and alert message the broker records goes through here
+ * first. A `string` variable reaches a strategy call as its Series, which holds
+ * the whole runtime (`ctx.__sandbox`); stored as is, it made the result
+ * impossible to `postMessage`.
+ */
+export declare function text(x: any): string;
+/**
+ * A strategy call's direction as the broker spells it.
+ *
+ * v1-v4 name the argument `long` and it is a bool: "true for buy, false for
+ * sell". From v5 it is `direction`, which is `strategy.long` or
+ * `strategy.short` -- here the strings "long" and "short". Both reach the same
+ * parameter, so a bool is mapped and anything else is passed through as text.
+ */
+export declare function directionOf(x: any): string;

package/dist/types/runtime/v1/constDefault.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Passed by the emitter as `str.tostring`'s second argument, in place of a
+ * format, when the call has no format and its value is a compile-time CONSTANT
+ * number. TradingView prints a constant and a series differently (see
+ * `numberToString` in ./stdlib/str.ts), and that is a property of the source,
+ * not of the value.
+ *
+ * Its own file rather than an export of str.ts, because the stdlib registry
+ * generator turns every export of a stdlib module into a built-in.
+ */
+export declare const CONST_DEFAULT = "\0const";