Skip to content

Commit 28ad088

Browse files
luisleo526claude
andcommitted
docs: add Part 3 (cross-cutting behaviors) to engine cheatsheet
Completeness audit (adversarial, source-checked) found the doc strong on fill mechanics but thin on cross-cutting behaviors. Adds Part 3: PnL/accounting model (pointvalue ignored, equity defs, min_equity reset, commission/pnl_pct), order APIs Part 2 omitted (cancel, RAW_ORDER, trail caveats, entry-bar wrong-side-exit skip, partial one-shot), bar/barstate + Series-500 cap, TF aggregation completion + gap bucket-flush, session/tz (bare hour=UTC, pre/postmarket hardcoded), MTF gaps_on, NA handling, -ffp-contract=off determinism, C-ABI report surface, multi-run reset matrix, run_strategy.py override foot-gun. Flags a possible double-slippage in close_opposite_then_enter. Header de-staled (PR #25 merged to main). Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
1 parent a4ab775 commit 28ad088

1 file changed

Lines changed: 143 additions & 12 deletions

File tree

‎docs/cheatsheet-runtime-and-execution.md‎

Lines changed: 143 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,16 @@
11
# PineForge Engine — Runtime Overrides & Order-Execution Cheatsheet
22

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.
107
118
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:
1310

1411
1. [Runtime-overrideable parameters](#part-1--runtime-overrideable-parameters)
1512
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)
2014

2115
---
2216

@@ -304,3 +298,140 @@ timestamp — see `engine_run.cpp` dispatch comment.)
304298
10. Under LTF/real-time, stamp fills with the **sub-bar** time, not the aggregate bar.
305299
11. Market vs priced timing: market next-open (POOC off) / this-close (POOC on); priced waits a bar.
306300
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

Comments
 (0)