|
1 | 1 | # PineForge Engine — Runtime Overrides & Order-Execution Cheatsheet |
2 | 2 |
|
3 | | -> **Source-verified.** Every claim was adversarially checked against the code |
4 | | -> (file:line) on `feat/input-source-syminfo-issues` (engine) / |
5 | | -> `feat/input-source-color-syminfo` (codegen). Corrections from that pass are |
6 | | -> folded in (notably: `engine_chart_timezone` is validator-only not a harness |
7 | | -> key; the `pending_close_qty_in_bar_` reset is in the outer bar loop not |
8 | | -> `dispatch_bar`; stop-entry mintick rounding is skipped on gap fills; |
9 | | -> `PERCENT_OF_EQUITY` includes open profit only on the explicit-`qty_type` path). |
| 3 | +> **Source-verified** against `main` (engine PR #25 merged; codegen PR #18). |
| 4 | +> Every Part 1/2 claim was adversarially checked (file:line). Part 3 collects |
| 5 | +> cross-cutting behaviors + caveats a forward executor needs (also audited). |
| 6 | +> File:line refs are approximate — grep the symbol. |
10 | 7 |
|
11 | 8 | Reference for driving the engine and for building a **forward / real-time** |
12 | | -executor that matches backtest semantics. Two parts: |
| 9 | +executor that matches backtest semantics. Three parts: |
13 | 10 |
|
14 | 11 | 1. [Runtime-overrideable parameters](#part-1--runtime-overrideable-parameters) |
15 | 12 | 2. [Order-execution rules](#part-2--order-execution-rules) (the hard part) |
16 | | - |
17 | | -> Surface note: `get_input_source`, `strategy_set_syminfo_timezone/_session/_metadata` |
18 | | -> land with the input.source/syminfo feature (engine PR #25 + codegen PR #18). |
19 | | -> Everything else is on `main`. File:line refs are approximate — grep the symbol. |
| 13 | +3. [Cross-cutting behaviors & caveats](#part-3--cross-cutting-behaviors--caveats) |
20 | 14 |
|
21 | 15 | --- |
22 | 16 |
|
@@ -304,3 +298,140 @@ timestamp — see `engine_run.cpp` dispatch comment.) |
304 | 298 | 10. Under LTF/real-time, stamp fills with the **sub-bar** time, not the aggregate bar. |
305 | 299 | 11. Market vs priced timing: market next-open (POOC off) / this-close (POOC on); priced waits a bar. |
306 | 300 | 12. Reused handle keeps risk state — reset/recreate per session if you don't want carryover. |
| 301 | + |
| 302 | +--- |
| 303 | + |
| 304 | +# Part 3 — Cross-cutting behaviors & caveats |
| 305 | + |
| 306 | +Audited gaps a forward/real-time executor must know (beyond per-order fills). |
| 307 | + |
| 308 | +## 3.1 PnL / accounting model |
| 309 | + |
| 310 | +- **`pointvalue` is IGNORED in all PnL math.** Raw PnL = `(exit−entry)·qty` |
| 311 | + everywhere (`engine_orders.cpp:277-279`); `syminfo_.pointvalue` is stored but |
| 312 | + never read. Futures/FX (ES=$50/pt, etc.) come out N× wrong unless you scale |
| 313 | + prices externally. `currency`/`basecurrency` are also decoration — no FX |
| 314 | + conversion. |
| 315 | +- **Two equity definitions.** `current_equity() = initial_capital_ + |
| 316 | + net_profit_sum_` (closed PnL; `strategy.equity` reads this). Explicit |
| 317 | + `qty_type=percent_of_equity` sizing adds `open_profit(close)`; default sizing |
| 318 | + does not. |
| 319 | +- **`update_equity_extremes()` runs once per bar AFTER on_bar**; samples |
| 320 | + `initial_capital_+net_profit_sum_+open_profit(close)`. On a new equity peak, |
| 321 | + `min_equity_` is **reset to the peak** → `max_runup_` measures from the most |
| 322 | + recent trough (TV behavior), not inception. |
| 323 | +- **`pnl_pct` excludes commission** (`pnl` includes both sides). `CASH_PER_ORDER` |
| 324 | + commission is charged **in full per partial-exit slice** (multi-leg pyramids |
| 325 | + overpay). `open_trade_*` deduct entry commission only. |
| 326 | +- **`calc_qty` fallback:** when `fill_price ≤ 0`, percent/cash sizing silently |
| 327 | + returns `default_qty_value_` (phantom size on bad data). |
| 328 | + |
| 329 | +## 3.2 Order APIs the doc's Part 2 omits |
| 330 | + |
| 331 | +- **`strategy.cancel(id)` / `strategy.cancel_all()`** exist |
| 332 | + (`engine_strategy_commands.cpp:367-376`): remove pending orders by id / clear |
| 333 | + all — **including EXIT/bracket orders**, same-bar ones too. |
| 334 | +- **`RAW_ORDER`** (`strategy.order`): bypasses margin gate, intraday-cap |
| 335 | + placement gate, and deferred-flip carry; closes-only into an opposite position |
| 336 | + (no re-entry); same pyramiding bypasses as ENTRY; OCA-cancel fires on any fill |
| 337 | + for NaN-qty siblings. |
| 338 | +- **Trail caveats:** `trail_price` param is **accepted but ignored**; |
| 339 | + `trail_points`/`trail_offset` are `ceil`-ed to whole ticks before computing |
| 340 | + the activation level; **no-offset trail** (`exits_at_activation`) fires at the |
| 341 | + activation level itself; `trail_best_price_` resets to `close` on the first |
| 342 | + `strategy.exit` for an id (preserved on re-issue). |
| 343 | +- **Entry-bar wrong-side exit:** non-magnifier, an exit whose stop is on the |
| 344 | + wrong side of entry is **silently skipped** on the entry bar (na-stop guard); |
| 345 | + magnifier evaluates it (gap-fills at sub-bar open). |
| 346 | +- **`consumed_partial_exit_ids_`:** a partial exit id is one-shot for the whole |
| 347 | + open-position lifetime — re-issuing same-id partial each bar is dropped until |
| 348 | + flat/new position. |
| 349 | + |
| 350 | +## 3.3 Bar lifecycle & barstate |
| 351 | + |
| 352 | +- `barstate.isfirst = (bar_index_==0)`; `isnew = is_first_tick_`; |
| 353 | + `isconfirmed = is_last_tick_`; `ishistory = true`; `isrealtime = false`; |
| 354 | + `islast/islastconfirmedhistory = barstate_islast_`. Engine has **no |
| 355 | + history-vs-realtime** concept; `on_bar` runs **once per script bar** (no |
| 356 | + `calc_on_every_tick`). |
| 357 | +- `Series<T>` default depth = **500 bars**; `max_bars_back` is silently dropped |
| 358 | + → lookbacks > 500 return `na`. |
| 359 | +- The **simple `run(bars,n)`** entry point does NOT set session predicates |
| 360 | + (`session.ismarket/isfirstbar/islastbar` stay false) — use the TF-aware |
| 361 | + overload if the script uses sessions. |
| 362 | +- `session.islastbar` is always `false` under the magnifier; in simple mode it's |
| 363 | + computed by **next-bar lookahead** — a live feed has no `i+1`, infer from the |
| 364 | + session string instead. |
| 365 | + |
| 366 | +## 3.4 Timeframe aggregation (input_tf < script_tf) |
| 367 | + |
| 368 | +- **CALENDAR (D/W/M):** a period completes on the **last input bar of the |
| 369 | + period** (next-bar-would-cross test), stamped at that bar — not on the next |
| 370 | + period's first bar. |
| 371 | +- **RATIO + feed gaps:** the bucket flushes/completes when |
| 372 | + `timestamp/bucket_ms` changes, **even if sub-bar count < ratio** → missing |
| 373 | + input bars yield a short (partial) but correctly-merged script bar. |
| 374 | +- Script-bar timestamp = **first-present** sub-bar (see `engine_run.cpp` |
| 375 | + aggregation comment). |
| 376 | + |
| 377 | +## 3.5 Session / timezone |
| 378 | + |
| 379 | +- Bare `hour`/`minute`/`dayofweek` use **UTC** (`gmtime_r`) regardless of |
| 380 | + syminfo tz; `hour(time)` uses `syminfo_.timezone`; `hour(time,tz)` explicit. |
| 381 | + Intraday-cap rollover uses **chart_timezone_** (see §2.11). |
| 382 | +- `session.ispremarket`/`ispostmarket` windows are **hardcoded** 04:00 / 20:00 |
| 383 | + exchange-local. |
| 384 | + |
| 385 | +## 3.6 request.security / MTF (if used) |
| 386 | + |
| 387 | +- `gaps_on=true`: on a partial HTF bar the engine **clears** the security series |
| 388 | + to `na` (no stale carry). LTF emulation **synthesizes** sub-bars (ENDPOINTS), |
| 389 | + not real ticks. With `lookahead_on`, the first sub-bar of a period pushes, |
| 390 | + later ones `update()` the same slot. Security evaluators run **before** |
| 391 | + `on_bar` each input bar. |
| 392 | + |
| 393 | +## 3.7 NA / gaps |
| 394 | + |
| 395 | +- Engine is **feed-agnostic**: it dispatches every bar in the array, incl. |
| 396 | + NaN/zero OHLCV. **No NA-bar suppression** — filter junk bars upstream. |
| 397 | + |
| 398 | +## 3.8 Determinism |
| 399 | + |
| 400 | +- Build with **`-ffp-contract=off`** (CMake default) to match TV's no-FMA JS |
| 401 | + math — otherwise TA values (RMA/EMA) drift after many bars. Mintick rounding |
| 402 | + uses a `1e-9` boundary epsilon. |
| 403 | + |
| 404 | +## 3.9 Report surface (C ABI) |
| 405 | + |
| 406 | +- `pf_report_t`/`pf_trade_t` expose `entry/exit time/price`, `pnl`, `pnl_pct`, |
| 407 | + `is_long`, `qty`, `max_runup/drawdown` + run diagnostics. **No equity curve** |
| 408 | + and **no `entry_id`/`exit_id`/comments/`bar_index`** over the C ABI — those |
| 409 | + are C++-accessor-only. Derive equity/profit-factor/Sharpe from the trades. |
| 410 | +- `pf_version_get()` / `pf_version_string()` for ABI gating. |
| 411 | + |
| 412 | +## 3.10 Multi-run state (reused handle) |
| 413 | + |
| 414 | +- **Reset per run:** `max_equity_`/`min_equity_`→`initial_capital_`, security |
| 415 | + feed counters, aggregator state. |
| 416 | +- **NOT reset:** `trades_`, `net_profit_sum_`, win/loss/even counts, |
| 417 | + `cons_loss_day_count_`, `risk_halted_`, `intraday_pnl_`, position/pyramid |
| 418 | + state, `pending_orders_`, `trail_best_price_`, `consumed_partial_exit_ids_`, |
| 419 | + trace buffer. Walk-forward on one handle **accumulates** — recreate the handle |
| 420 | + per independent run. |
| 421 | + |
| 422 | +## 3.11 Harness foot-gun |
| 423 | + |
| 424 | +- `scripts/run_strategy.py` does **NOT** wire `strategy_set_override` — a |
| 425 | + `strategy()` key (e.g. `initial_capital`) placed in `inputs.json` is forwarded |
| 426 | + to `strategy_set_input` and silently no-ops. Use `docker/run_json.py` or the C |
| 427 | + ABI directly for `strategy()` overrides. CLI flags `--trace-json` and |
| 428 | + `--disable-trading-before-window` (→ `strategy_set_trade_start_time`) affect |
| 429 | + the run. |
| 430 | + |
| 431 | +## ⚠️ Possible bug (flagged, not confirmed) |
| 432 | + |
| 433 | +`close_opposite_then_enter` (`engine_orders.cpp:539`) calls `apply_slippage`, |
| 434 | +then `execute_partial_exit_qty` (`engine_orders.cpp:154-155`) applies it |
| 435 | +**again** → the bracket close-then-enter exit may be **double-slipped**. Masked |
| 436 | +in the corpus because all probes run `slippage=0` (double-rounding is |
| 437 | +idempotent there). Worth a targeted test before trusting slippage on that path. |
0 commit comments