Skip to content

Commit c45cf5a

Browse files
committed
refactor: move retained-parent priority into Pine compatibility
1 parent f864be5 commit c45cf5a

23 files changed

Lines changed: 562 additions & 237 deletions

‎CMakeLists.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@ endif()
7878
# === pineforge library =================================================
7979
add_library(pineforge STATIC
8080
src/c_abi.cpp
81+
src/compat/pine/order_priority.cpp
8182
src/engine_aux_security.cpp
8283
src/engine_fills.cpp
8384
src/engine_lower_tf.cpp

‎README.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,8 @@ live behavior or real broker fills.
125125
126126
## Validation scoreboard
127127
128+
**Native policy refactoring · 2026-09-10:** engine [#234](https://github.com/pineforge-4pass/pineforge-engine/pull/234) and codegen [#127](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/127) preserve **4,182 excellent / 8 strong**. Both the old-engine/new-codegen and new-engine/new-codegen Cloud runs retain all **4,190 raw trade CSVs, counts and full grades** unchanged. The target bands have zero entrants and zero leavers: **net 0, no individual regression**. These changes remove an unused source flag and give Pine cap behavior explicit ownership; they do not claim complete engine independence. The formal gates remain zero-improvement FAILs and the official baseline remains unchanged.
129+
128130
**Round 39 · 2026-09-09:** **4,182 excellent / 8 strong / zero moderate** across all **4,190 scored probes**. This round adds one excellent result, with zero regressions on any canonical metric.
129131
130132
| Board | Test set | Result | TradingView trades evaluated |
@@ -169,7 +171,7 @@ Every script is exported from TradingView as-is (its own inputs, its own default
169171
- **strong** — ≥ 95% matched, trade count within 6%, entries within 0.1% and exits within 0.5% at p90;
170172
- **moderate / weak** — ≥ 75% coverage, or less.
171173
172-
A grade is never one lucky run. Every candidate build is measured over the whole population on a reproducible cloud pipeline, each graded snapshot is published by content hash, and a build ships only through a deterministic gate: **no regression on any metric of any ETH 15m probe**, and, pooled over the other lanes, strictly more probes entering the excellent and excellent+strong bands than leaving them. Merges are fast-forwarded, so the commit that was gated is the commit on `main`.
174+
Published parity results use a fixed population and reproducible Cloud Run measurements. The formal gate requires **no hard-surface regression** and strictly positive pooled movement across the target excellent and excellent+strong bands. A documented native-correctness exception permits exactly zero target-band movement with no individual regression, after full comparison, independent review and CI; its actual FAIL remains recorded and baseline promotion is deferred. Negative movement is outside this exception. Baseline promotion requires a recorded PASS and an exact-head merge with green CI.
173175
174176
### What the closed test taught the engine
175177
@@ -206,6 +208,10 @@ PyneCore's 15 non-excellent strategies involve `strategy.exit(stop=…, limit=
206208

207209
---
208210

211+
Explicit Pine frontends must use the [execution attachment and regeneration
212+
contract](docs/pine-order-priority-boundary.md) for retained-parent priority.
213+
Bare native engines and cap-only generated constructors do not opt into it.
214+
209215
## What ships here
210216

211217
- `libpineforge.a` — the static runtime: order matching and fills, sizing and margin, the bar magnifier, 66 indicator classes, `request.security()`, time and session math.

‎docs/pages/abi-stability.md‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -112,12 +112,12 @@ notice:
112112
- The shape of internal log lines (use them for humans, not parsers).
113113

114114
Rebuild generated and native C++ objects against matching engine headers and
115-
runtime. The cap compatibility extraction changes the v2 object layout and
116-
therefore uses the internal `engine_script_run_v3` inline namespace. An object
115+
runtime. The cap and priority extractions change the v2/v3 object layouts and
116+
therefore use the internal `engine_script_run_v4` inline namespace. An object
117117
built from base `38dc73e` headers references v2 out-of-line members and must
118-
fail to link to this v3 runtime. The source-pairing check compiles frozen exact
118+
fail to link to this v4 runtime. The source-pairing check compiles frozen exact
119119
base headers separately before testing the link, so a missing include or
120-
compile failure cannot masquerade as mismatch protection. Both generated-style
120+
compile failure cannot masquerade as mismatch protection. Frozen f864/v3 headers are also rejected by this v4 runtime. Both generated-style
121121
and native-style current callers must still link.
122122

123123
`PINEFORGE_HAS_SCRIPT_RUN_PREPARE_V1` remains 1: it describes the existing hook
@@ -129,13 +129,13 @@ retrofit an old module. Public C function signatures, POD layouts,
129129
Namespace versioning protects referenced internal C++ symbols; it does not
130130
validate an erased `pf_strategy_t` handle. Use a handle only with functions from
131131
its creating strategy module. A fully self-contained old module can still use
132-
its own matching runtime; this check does not turn it into a v3 module.
132+
its own matching runtime; this check does not turn it into a v4 module.
133133

134-
The cap boundary also advances the broker fingerprint domain to
135-
`pineforge-broker-state/v3` and stream fingerprint version to 3. These identify
136-
changed serialized state, including the Pine configuration/quota/cause and
134+
The cap and priority boundaries advance the broker fingerprint domain to
135+
`pineforge-broker-state/v4` and stream fingerprint version to 4. These identify
136+
changed serialized state, including Pine priority attachment/configuration, cap quota/cause and
137137
separate generic close request. The Pine component schema remains 1; it is
138-
independent of the aggregate fingerprint version. Prior v2 fingerprints are
138+
independent of the aggregate fingerprint version. Prior v2/v3 fingerprints are
139139
not comparable. Fingerprints are replay checks, not serialized checkpoints or
140140
complete hashes of private strategy state. The native runner already binds
141141
its strategy-library SHA; its ledger format and Python provenance fingerprints

‎docs/pine-intraday-cap-boundary.md‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,10 @@ extracts those decisions from existing execution paths; it does not make the
77
engine independent of Pine or establish broader TradingView parity.
88

99
The paired codegen explicitly selects this compatibility component in the
10-
`GeneratedStrategy` constructor, guarded by
11-
`PINEFORGE_HAS_EXPLICIT_PINE_CAP_V1`. Older supported engines do not define
12-
that capability and keep their established default. Risk statements still
10+
`GeneratedStrategy` constructor. Current codegen uses the scoped
11+
`attach_pine_execution_adapter()` hook for cap and retained-parent priority,
12+
with a guarded cap-only fallback for older engines; see
13+
[pairing and regeneration](pine-order-priority-boundary.md). Risk statements still
1314
assign `max_intraday_filled_orders_ = (int)(expression)` at execution time;
1415
selecting a component does not evaluate or hoist a risk statement.
1516

@@ -117,18 +118,18 @@ Independent Grok, unchanged fixed Cloud controls and full regression/gate
117118
verification remain root-owned requirements before any parity or publication
118119
claim.
119120

120-
## Internal pairing and observable-state version 3
121+
## Internal pairing and observable-state version 4
121122

122123
Relative to base `38dc73e`, the new policy/obligation members change the
123-
`BacktestEngine` layout. Its inline namespace is now `engine_script_run_v3`;
124+
`BacktestEngine` layout. Its inline namespace is now `engine_script_run_v4`;
124125
base-header v2 native/generated objects must fail to link against this runtime.
125126
The exact source-pairing test compiles frozen base headers and checks explicit
126-
undefined v2 symbols, alongside matched v3 positive controls. Its isolated v2
127+
undefined v2 symbols, alongside matched v4 positive controls. Its isolated v2
127128
symbol stub is a reverse-link control, not a build of the entire old runtime.
128129
No mismatch test program is executed.
129130

130-
Broker hashes use `pineforge-broker-state/v3`; stream fingerprints begin with
131-
version3. The Pine policy's own schema stays1. Public C ABI version4, stream API
131+
Broker hashes use `pineforge-broker-state/v4`; stream fingerprints begin with
132+
version 4. Each Pine component's own schema remains 1. Public C ABI version4, stream API
132133
version1, POD layouts, exports and `PINEFORGE_HAS_SCRIPT_RUN_PREPARE_V1` remain
133134
unchanged. This version correction changes linking and serialized hash bytes,
134135
not cap charging, fill prices or other economic behavior. It does not make
@@ -151,3 +152,5 @@ separating requests, execution facts and exposure state; they do not establish
151152
Pine quota policy or predictable live fills. See [MQL5 OrderSend](https://www.mql5.com/en/docs/trading/ordersend)
152153
and [OnTradeTransaction](https://www.mql5.com/en/docs/event_handlers/ontradetransaction).
153154
This patch adds no external execution adapter or callback-ordering model.
155+
156+
The priority attachment adds a v3/f864 frozen-header rejection control; the cap-only API and its financial rules retain their scope. See [order-priority ownership](pine-order-priority-boundary.md).
Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Explicit Pine execution attachment and order priority
2+
3+
`BacktestEngine::attach_pine_execution_adapter()` explicitly selects two
4+
compatibility components: the existing intraday cap and retained-parent order
5+
priority. It is idempotent, preserves configuration and outstanding cap state,
6+
and does not imply that all Pine behavior has been extracted from the engine.
7+
`enable_pine_intraday_cap()`, the cap constructor argument and legacy integer
8+
cap assignments remain cap-only operations.
9+
10+
Bare construction leaves order priority detached. Syminfo metadata, including
11+
`flat_retained_child_fresh_parent_order=1`, cannot attach it. The Pine component
12+
owns that key's finite-positive interpretation and retains a supplied value
13+
while detached; explicit attachment preserves a prior off override. Under Pine
14+
attachment, an absent key enables the exact historical exception. Zero, negative
15+
and nonfinite supplied values disable it. Copy/reset preserve attachment and
16+
configuration without retaining a cached scheduling decision.
17+
18+
The full predicate lives in `src/compat/pine/order_priority.cpp`: exact two-object
19+
book, ordinary POOC context, flat placement, named-cancel and exact child-reissue
20+
receipts, adjacent incarnations, default quantities, full absolute stop+limit
21+
child, pure-stop parent, prior-bar age and all OCA/callback/magnifier/stream
22+
exclusions. Three/four unrelated orders and an intervening accepted-and-canceled
23+
order remain exclusions. This is one active rule transferred to Pine ownership,
24+
not a claim that its source-shape policy disappeared globally.
25+
26+
The comparator consumes an immutable `broker::OrderPriorityDecision` bound to
27+
exact incarnations. It substitutes two sequence tie-breaks at their former
28+
location, after fill phase. It does not change eligibility, fill prices, OCA
29+
mutation, callbacks, admission or financial accounting. Shared incarnation
30+
receipts and their other compatibility consumers remain unchanged.
31+
32+
## Pairing and regeneration
33+
34+
New codegen calls the fully qualified attachment method in the constructor,
35+
before `strategy_create` returns and host metadata arrives:
36+
37+
```cpp
38+
#if defined(PINEFORGE_HAS_EXPLICIT_PINE_EXECUTION_ADAPTER_V1)
39+
pineforge::BacktestEngine::attach_pine_execution_adapter();
40+
#elif defined(PINEFORGE_HAS_EXPLICIT_PINE_CAP_V1)
41+
pineforge::BacktestEngine::enable_pine_intraday_cap();
42+
#endif
43+
```
44+
45+
The fallback preserves existing cap-only engines' native-to-Pine cap selection
46+
and their old default retained-parent rule. Engines lacking both capabilities
47+
use their established defaults. This is generated-source portability with
48+
matching headers/runtime, not binary compatibility across engine versions.
49+
50+
Old cap-only generated source can compile with current headers but does **not**
51+
select the priority exception. Regenerate it with the paired codegen, or
52+
explicitly update a maintained C++ Pine frontend to call the attachment method
53+
before metadata. Neither metadata nor an implicit constructor default repairs
54+
old source. Existing checked-in corpus/tutorial C++ must likewise be regenerated
55+
before using it for Pine behavior measurements; compilation alone is insufficient.
56+
57+
Rebuild every C++ consumer with matching current headers and archive. The class
58+
namespace is `engine_script_run_v4`; frozen v2/base38 and v3/f864 callers are
59+
compile/link rejection controls. Broker fingerprint domain and stream fingerprint
60+
version are now 4 and include priority attachment/configuration. Prior hashes
61+
are not comparable. Public C functions, PODs and ABI/API versions are unchanged;
62+
an erased handle still belongs to its creating module.
63+
64+
## Remaining native gap and evidence limits
65+
66+
Bare native execution retains the ordinary phase/sequence scan. An older child
67+
visited while flat can still be skipped until a later pass, exposing a transient
68+
position to the intervening close-time observer. No identity-bound child
69+
activation/event queue has been added. That causal scheduler is a separate next
70+
slice, not an unused reducer in this extraction.
71+
72+
Literal C++ controls preserve the old Pine price, quantity, timing and financial
73+
assertions with explicit fixture attachment; they separately pin native metadata
74+
inertness, exclusions, OCA, copy/reset/hash and current lifetime safety. Codegen
75+
checks compile source only. None establishes TV truth, measured campaign
76+
neutrality, actualZERO, absence of population regressions or readiness to publish.
Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
#pragma once
2+
#include "../../order_priority.hpp"
3+
#include <cmath>
4+
#include <optional>
5+
#include <string>
6+
#include <vector>
7+
8+
namespace pineforge { struct PendingOrder; }
9+
namespace pineforge::compat::pine {
10+
11+
struct OrderPriorityContext {
12+
bool broker_flat;
13+
bool process_orders_on_close;
14+
bool calc_on_order_fills;
15+
bool coof_scheduler_active;
16+
bool bar_magnifier_enabled;
17+
bool stream_warmup_mode;
18+
bool stream_idle;
19+
int bar_index;
20+
};
21+
22+
// Pine's bounded retained-child/recreated-parent exception. The complete
23+
// source-shape rule lives in this component; this is an ownership transfer,
24+
// not a generic native activation/dependency scheduler.
25+
class OrderPriority {
26+
public:
27+
static constexpr uint64_t schema_version = 1;
28+
void attach() { attached_ = true; }
29+
bool attached() const { return attached_; }
30+
bool retained_parent_first() const { return retained_parent_first_; }
31+
void metadata(const std::string& key, double value) {
32+
// One declaration owner, including values received while detached.
33+
// Metadata never selects Pine execution. Reattachment preserves off.
34+
if (key == "flat_retained_child_fresh_parent_order")
35+
retained_parent_first_ = std::isfinite(value) && value > 0.0;
36+
}
37+
std::optional<broker::OrderPriorityDecision> select(
38+
const OrderPriorityContext& ctx,
39+
const std::vector<PendingOrder>& book) const;
40+
private:
41+
bool attached_ = false;
42+
bool retained_parent_first_ = true;
43+
};
44+
45+
} // namespace pineforge::compat::pine

‎include/pineforge/engine.hpp‎

Lines changed: 18 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
#include "bar.hpp"
1515
#include "broker_events.hpp"
1616
#include "compat/pine/intraday_cap.hpp"
17+
#include "compat/pine/order_priority.hpp"
1718
#include "series.hpp"
1819
#include "timeframe.hpp"
1920
#include "magnifier.hpp"
@@ -36,6 +37,8 @@
3637
// Generated constructors can explicitly select Pine cap compatibility before
3738
// any host metadata setter. Older engines keep their legacy default behavior.
3839
#define PINEFORGE_HAS_EXPLICIT_PINE_CAP_V1 1
40+
// Explicitly selects cap and retained-parent priority compatibility only.
41+
#define PINEFORGE_HAS_EXPLICIT_PINE_EXECUTION_ADAPTER_V1 1
3942

4043
namespace pineforge {
4144

@@ -1100,10 +1103,10 @@ struct StrategyOverrides {
11001103

11011104
// The C++ subclass contract is internal, unlike pineforge.h's stable C ABI.
11021105
// Changing its layout or vtable requires all generated/native C++ objects to be rebuilt.
1103-
// v3 replaces the v2 cap scalars with a Pine policy and a close obligation.
1104-
// Version the mangled class name so a v2 header's member offsets/vtable cannot
1106+
// v4 adds detached Pine order-priority ownership to the v3 cap boundary.
1107+
// Version the mangled class name so older headers' member offsets/vtable cannot
11051108
// silently bind out-of-line members of this different object layout.
1106-
inline namespace engine_script_run_v3 {
1109+
inline namespace engine_script_run_v4 {
11071110
class BacktestEngine {
11081111
protected:
11091112
// --- Position state ---
@@ -1282,15 +1285,9 @@ class BacktestEngine {
12821285
// Historical fill-triggered recalculation is strictly opt-in. The false
12831286
// branch in dispatch_bar remains the legacy control path.
12841287
bool calc_on_order_fills_ = false;
1285-
// Narrow ordinary-POOC broker ordering rule for one exact book shape:
1286-
// while truly flat, a single reissued from_entry bracket can retain an
1287-
// older sequence slot than its same-source-bar pure-stop parent after the
1288-
// prior parent was explicitly cancelled and freshly recreated.
1289-
// That exact two-order book scans the parent first so the child can inspect
1290-
// the post-entry path before the close-time script body. The metadata key
1291-
// remains as an explicit A/B override; ordinary execution enables the
1292-
// TV-pinned rule by default.
1293-
bool flat_retained_child_fresh_parent_order_ = true;
1288+
// Detached on bare native construction. Only the explicit Pine frontend
1289+
// attachment can select its source-shape priority interpretation.
1290+
compat::pine::OrderPriority pine_order_priority_;
12941291
QtyType default_qty_type_ = QtyType::FIXED;
12951292
double default_qty_value_ = 1.0;
12961293
int pyramiding_ = 1; // max additional entries in same direction
@@ -4497,6 +4494,13 @@ class BacktestEngine {
44974494
// Explicit frontend selection, not a generic native risk switch. This
44984495
// preserves any prior declaration values and does not reset quota/state.
44994496
void enable_pine_intraday_cap() { max_intraday_filled_orders_.attach(); }
4497+
// Current execution-adapter scope: intraday cap + retained-parent priority.
4498+
// Idempotent configuration attachment, not a reset or universal Pine mode.
4499+
// Generated constructors call this before any host metadata is forwarded.
4500+
void attach_pine_execution_adapter() {
4501+
max_intraday_filled_orders_.attach();
4502+
pine_order_priority_.attach();
4503+
}
45004504
virtual ~BacktestEngine() = default;
45014505
virtual void on_bar(const Bar& bar) = 0;
45024506

@@ -4795,10 +4799,7 @@ class BacktestEngine {
47954799
margin_zero_cover_full_liquidation_ =
47964800
std::isfinite(value) && value > 0.0;
47974801
}
4798-
if (key == "flat_retained_child_fresh_parent_order") {
4799-
flat_retained_child_fresh_parent_order_ =
4800-
std::isfinite(value) && value > 0.0;
4801-
}
4802+
pine_order_priority_.metadata(key, value);
48024803
// Forward through the real base setter used by the C ABI. A selected
48034804
// frontend owns recognition and numeric validation; no derived shadow
48044805
// setter or cap-key interpretation belongs in this transport.
@@ -5141,5 +5142,5 @@ class BacktestEngine {
51415142
void trace(const std::string& name, int value) { trace(name, static_cast<double>(value)); }
51425143
};
51435144

5144-
} // inline namespace engine_script_run_v3
5145+
} // inline namespace engine_script_run_v4
51455146
} // namespace pineforge
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
#pragma once
2+
#include <array>
3+
#include <cstdint>
4+
5+
namespace pineforge::broker {
6+
7+
// Immutable assignments bound to exact pending objects, not reusable user IDs.
8+
// A decision changes only the sequence tie-break, never phase or eligibility.
9+
struct OrderPriorityAssignment {
10+
uint64_t incarnation;
11+
int64_t sequence;
12+
};
13+
struct OrderPriorityDecision {
14+
std::array<OrderPriorityAssignment, 2> assignments;
15+
int64_t sequence(uint64_t incarnation, int64_t fallback) const {
16+
for (const auto& assignment : assignments) {
17+
if (assignment.incarnation == incarnation) return assignment.sequence;
18+
}
19+
return fallback;
20+
}
21+
};
22+
23+
} // namespace pineforge::broker

0 commit comments

Comments
 (0)