Skip to content

Commit f268342

Browse files
authored
feat: add historical account FX lifecycle (#125)
1 parent 76e8097 commit f268342

23 files changed

Lines changed: 1572 additions & 66 deletions

‎README.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ for the full tool catalog, request schemas, and env vars (`PINEFORGE_ALLOW_ANYWH
120120

121121
- 🎯 **TradingView-exact.** 251 of 252 reference strategies match TV trade-for-trade. The lone outlier is a stress probe at the 1× margin boundary where TV's broker emulator is non-deterministic — engine is correct. **100 of 100** PineForge excellent vs PyneCore + PineTS on the public three-way benchmark (~167,000 TV trades; PyneCore: 85 of 100; PineTS indicator-only).
122122
- ⚡ **Microsecond-class.** Median **162× faster than PyneCore** across 99 commonly-timed strategies (full 41,307-bar OHLCV, magnifier-on hot loop; see [benchmarks/results/speed.md](benchmarks/results/speed.md)). Parameter sweeps load one `.so` and re-run with new inputs — no recompile, no fork, no IPC.
123-
- 🔒 **Stable C ABI.** 26 functions, one header (`<pineforge/pineforge.h>`). Append-only across minor versions, `static_assert`-pinned struct layouts, hidden-visibility hygiene. Drop a strategy `.so` in any harness; it just runs.
123+
- 🔒 **Stable C ABI.** 27 functions, one header (`<pineforge/pineforge.h>`). Append-only across minor versions, `static_assert`-pinned struct layouts, hidden-visibility hygiene. Drop a strategy `.so` in any harness; it just runs.
124124
- 🧪 **Reproducible to the bit.** Deterministic float ordering, deterministic bar magnifier, no internal RNG seeded from time. Two runs with the same inputs produce bit-identical trade lists.
125125
- 🧰 **FFI-friendly.** Call from Python (`ctypes`), Rust (`libloading`), Go (`cgo`), Node, Julia. Worked examples for [pure C](https://cdocs.pineforge.dev/examples_c.html), [Python sweep](https://cdocs.pineforge.dev/examples_python_sweep.html), [Rust](https://cdocs.pineforge.dev/examples_rust.html), [multi-strategy harness](https://cdocs.pineforge.dev/examples_multi.html), and [magnifier A/B](https://cdocs.pineforge.dev/examples_magnifier.html) ship in the docs.
126126
- 🌍 **Cross-platform CI.** Linux + macOS × Release + Debug. Universal mac binary. Static library, no runtime DSO surprises at deploy time.
@@ -129,7 +129,7 @@ for the full tool catalog, request schemas, and env vars (`PINEFORGE_ALLOW_ANYWH
129129

130130
## For developers: embed the runtime directly
131131

132-
PineForge ships as a static C library (`libpineforge.a`) with a stable 26-symbol C ABI. Call from C, Python, Rust, Go, Node, Julia — one harness, swap strategies forever.
132+
PineForge ships as a static C library (`libpineforge.a`) with a stable 27-symbol C ABI. Call from C, Python, Rust, Go, Node, Julia — one harness, swap strategies forever.
133133

134134
### See it in 30 seconds
135135

@@ -337,6 +337,7 @@ int main(void) {
337337
| `strategy_set_syminfo_mintick` | Set symbol tick size |
338338
| `strategy_set_syminfo_pointvalue` | Set symbol point value |
339339
| `strategy_set_syminfo_metadata` | Inject numeric symbol metadata |
340+
| `strategy_set_account_currency_fx_series`| Set effective-time quote-to-account FX |
340341
| `strategy_get_last_error` | Read the latest runtime error |
341342
| `pf_version_get` | Runtime version |
342343
| `pf_abi_version` | Struct-layout version (`PF_ABI_VERSION`) |
@@ -397,7 +398,7 @@ cmake/smoke_consumer/ - Minimal find_package(PineForge) CI smoke project
397398
398399
## Visibility hygiene
399400
400-
Every compiled strategy `.so` that statically links `libpineforge.a` exports **exactly the 26 documented C ABI symbols** and zero internal C++ symbols. This is enforced at the library level:
401+
Every compiled strategy `.so` that statically links `libpineforge.a` exports **exactly the 27 documented C ABI symbols** and zero internal C++ symbols. This is enforced at the library level:
401402
402403
- `libpineforge.a` is built with `-fvisibility=hidden -fvisibility-inlines-hidden`
403404
- Public symbols are tagged `PF_API` (visibility=default)

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

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ recompiling. "Compile-time" = baked into `generated.cpp` from the Pine
3333
| `strategy_set_syminfo_timezone(s, tz)` | `UTC` | Exchange TZ → feeds `session.ismarket` / `time(session)`. **Separate slot** from chart tz. |
3434
| `strategy_set_syminfo_session(s, str)` | `24x7` | Session string e.g. `0930-1600:23456` (days 1=Sun..7=Sat). |
3535
| `strategy_set_syminfo_metadata(s, key, double)` | reads `na` | Inject a fundamental field (`shares_outstanding_total`, `target_price_*`, …); engine only computes — data fed externally. |
36+
| `strategy_set_account_currency_fx_series(s, timestamps, rates, n)` | scalar metadata fallback | Copy a strictly increasing effective-time quote-to-account FX curve. Selection is inclusive as-of, carries forward, and uses the scalar fallback before the first point. Curve presence selects the converted-currency broker ledger even when the effective rate equals 1. Passing `n=0` clears it. Ordinary historical, non-COOF, non-magnifier runs only; a broker-open rate change on a margin-call-enabled carried position is supported for TV-pinned 1x longs, while carried shorts and leveraged positions fail closed. |
3637

3738
Run entry points: `run_backtest(s,bars,n,out)` (auto-detect TF, no magnifier) /
3839
`run_backtest_full(s,bars,n,input_tf,script_tf,bar_magnifier,magnifier_samples,magnifier_dist,out)`.
@@ -94,7 +95,12 @@ Any non-meta key → `strategy_set_input`. Recognized: `ohlcv_csv`,
9495
`ohlcv_start_ms`, `script_tf`, `input_tf`, `chart_timezone`, and a
9596
`runtime_overrides` block: `bar_magnifier`, `magnifier_distribution`,
9697
`magnifier_samples`, `magnifier_volume_weighted`, `timezone`, `session`,
97-
`syminfo_metadata`. `tv_trades_csv` / `tv_trades_csv_tz` are verify-only.
98+
`syminfo_metadata`, `account_currency_fx_daily_close_json`.
99+
The FX JSON is a non-empty `{\"YYYY-MM-DD\": close}` object. The adapter sorts
100+
dates and makes day D's UTC close effective at D+1 00:00 UTC; the latest point
101+
whose effective timestamp is at or before the broker event carries forward.
102+
Duplicate dates and non-positive/non-finite rates fail closed. The Docker runner
103+
does not support this input. `tv_trades_csv` / `tv_trades_csv_tz` are verify-only.
98104

99105
> `engine_chart_timezone` is **NOT** a `run_strategy.py` key — it's consumed
100106
> only by the private canonical validator. In this harness use `chart_timezone`.

‎docs/coverage.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@
6060
## Public C ABI
6161

6262
`<pineforge/pineforge.h>` is the **single canonical consumer header**.
63-
Every compiled PineForge strategy `.so` exports exactly the 26 symbols
63+
Every compiled PineForge strategy `.so` exports exactly the 27 symbols
6464
declared there:
6565

6666

@@ -88,6 +88,7 @@ declared there:
8888
| `strategy_set_syminfo_mintick` | Instrument tick size (`syminfo.mintick`) |
8989
| `strategy_set_syminfo_pointvalue` | Futures $-per-point multiplier (`syminfo.pointvalue`) |
9090
| `strategy_set_syminfo_metadata` | Inject fundamental / exchange metadata by Pine member name |
91+
| `strategy_set_account_currency_fx_series`| Effective-time quote-to-account conversion curve |
9192
| `strategy_get_last_error` | Error message from the most recent failed run |
9293
| `pf_version_get` | Runtime version (struct) |
9394
| `pf_abi_version` | Caller-allocated POD layout version |
@@ -119,7 +120,7 @@ single `.hpp`):
119120

120121
| Module | Header | Source | Pine-facing role |
121122
| ------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
122-
| Public C ABI | `pineforge.h` | `c_abi.cpp` (+ layout `static_assert`s) | The 26 documented C symbols every compiled strategy `.so` exports. |
123+
| Public C ABI | `pineforge.h` | `c_abi.cpp` (+ layout `static_assert`s) | The 27 documented C symbols every compiled strategy `.so` exports. |
123124
| Engine | `engine.hpp` | `engine_run.cpp`, `engine_stream.cpp`, `engine_orders.cpp`, `engine_fills.cpp`, `engine_path_resolve.cpp`, `engine_strategy_commands.cpp`, `engine_trade_accessors.cpp`, `engine_security.cpp`, `engine_lower_tf.cpp`, `engine_risk.cpp`, `engine_report.cpp` | One-shot and continuous lifecycle, orders, raw-trade/bar fills, risk, reports, inputs / syminfo, magnifier, TF aggregation, and `request.security` plumbing. |
124125
| Engine internals | `engine_internal.hpp` | (private cross-TU header) | `pineforge::internal::`* types and helpers shared between engine `.cpp` partitions; not part of the public ABI. |
125126
| Technical analysis | `ta.hpp` | `ta_moving_averages.cpp`, `ta_oscillators.cpp`, `ta_volatility_trend.cpp`, `ta_extremes_volume.cpp`, `ta_misc.cpp` | Official `ta.`* functions and series variables backed by stateful runtime classes with `compute` / `recompute`, plus `pivot_point_levels(...)` free function. |

‎docs/pages/abi-stability.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ Three layers:
5454

5555
## Symbol inventory
5656

57-
A compiled strategy `.so` exports **exactly these 26 C symbols** and
57+
A compiled strategy `.so` exports **exactly these 27 C symbols** and
5858
zero internal C++ symbols:
5959

6060
| Symbol | Group |
@@ -81,6 +81,7 @@ zero internal C++ symbols:
8181
| `strategy_set_syminfo_mintick` | @ref pf_config |
8282
| `strategy_set_syminfo_pointvalue` | @ref pf_config |
8383
| `strategy_set_syminfo_metadata` | @ref pf_config |
84+
| `strategy_set_account_currency_fx_series` | @ref pf_config |
8485
| `strategy_get_last_error` | Diagnostics |
8586
| `pf_version_get` | @ref pf_version |
8687
| `pf_abi_version` | @ref pf_version |

‎docs/pages/index.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -80,18 +80,18 @@ End-to-end, runnable examples that go beyond the MACD tutorial:
8080

8181
## API at a glance
8282

83-
The entire public surface fits in **one header** and **26 functions**:
83+
The entire public surface fits in **one header** and **27 functions**:
8484

8585
| Group | Symbols | Reference |
8686
| --- | --- | --- |
8787
| Lifecycle | `strategy_create`, `strategy_free`, `run_backtest`, `run_backtest_full`, `report_free` | @ref pf_lifecycle |
8888
| Streaming | `strategy_stream_begin`, `strategy_stream_push_tick`, `strategy_stream_push_ticks`, `strategy_stream_advance_time`, `strategy_stream_end`, `strategy_stream_fill_report` | @ref pf_streaming |
89-
| Configuration | Inputs, strategy overrides, tracing, trade start, chart / symbol timezone, session, tick size, point value, and numeric metadata | @ref pf_config |
89+
| Configuration | Inputs, strategy overrides, tracing, trade start, chart / symbol timezone, session, tick size, point value, numeric metadata, and timestamped account-currency FX | @ref pf_config |
9090
| Diagnostics | `strategy_get_last_error` | #strategy_get_last_error |
9191
| Version | `pf_version_get`, `pf_abi_version`, `pf_version_string` | @ref pf_version |
9292
| Types | `pf_bar_t`, `pf_trade_tick_t`, `pf_trade_t`, `pf_report_t`, metrics, diagnostics, trace, equity, version, and `pf_magnifier_distribution_t` | @ref pf_types |
9393

94-
Every PineForge-generated strategy `.so` exports exactly these 26 symbols
94+
Every PineForge-generated strategy `.so` exports exactly these 27 symbols
9595
and zero internal C++ symbols — see
9696
**[ABI stability](@ref abi_stability)** for the full guarantee.
9797

0 commit comments

Comments
 (0)