Skip to content

Commit f864be5

Browse files
committed
refactor: isolate Pine cap policy from native order state
1 parent d1cc7d8 commit f864be5

30 files changed

Lines changed: 2331 additions & 481 deletions

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,8 +61,10 @@ Sentinels for "not overridden": `NaN` (doubles), `-1` (ints).
6161
| `close_entries_rule` | FIFO | `ANY`/`any`/`1` = ANY, else FIFO |
6262

6363
**Compile-time only (no override path):** `margin_long` / `margin_short`
64-
(default 100 = 1x). `script_has_strategy_close_` is retained only as a legacy
65-
generated-code compatibility bit and does not affect runtime behavior.
64+
(default 100 = 1x). Order behavior follows executed commands; the presence of
65+
an unreachable close call in source does not configure the broker. Regenerate
66+
older generated C++ that assigns the removed `script_has_strategy_close_`
67+
member before rebuilding against these headers.
6668

6769
## 1.3 `strategy.risk.*` — compile-time only
6870

‎docs/pages/abi-stability.md‎

Lines changed: 35 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -111,22 +111,41 @@ notice:
111111
- Internal symbol names (anything not tagged `PF_API`).
112112
- The shape of internal log lines (use them for humans, not parsers).
113113

114-
Rebuild generated C++ objects against matching engine headers and the runtime
115-
archive. The script-run preparation hook uses the internal
116-
`engine_script_run_v2` inline namespace, so an object compiled against the old
117-
`BacktestEngine` layout or vtable cannot silently bind the new runtime. Newly generated
118-
lifecycle-aware modules also require `PINEFORGE_HAS_SCRIPT_RUN_PREPARE_V1` at
119-
compile time. Regenerate and rebuild a strategy module to obtain complete
120-
script-state reset; replacing an archive does not retrofit an old module.
121-
These checks do not change the public C function signatures or POD layouts.
122-
123-
The owned-opening model uses broker fingerprint domain
124-
`pineforge-broker-state/v2` and stream fingerprint version 2. Fingerprints must
125-
be compared only for the same pinned engine build and configuration; prior
126-
fingerprints are not compatible with this representation. They are replay
127-
checks, not serialized checkpoints. The model removes four obsolete hashed
128-
labels and hashes the opening receipt's producer, position and checkpoint
129-
identity instead. Rebuild native/generated modules against the new headers.
114+
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
117+
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
119+
base headers separately before testing the link, so a missing include or
120+
compile failure cannot masquerade as mismatch protection. Both generated-style
121+
and native-style current callers must still link.
122+
123+
`PINEFORGE_HAS_SCRIPT_RUN_PREPARE_V1` remains 1: it describes the existing hook
124+
capability, not the class layout version. Regenerate and rebuild a strategy
125+
module to obtain complete script-state reset; replacing an archive does not
126+
retrofit an old module. Public C function signatures, POD layouts,
127+
`PF_ABI_VERSION` (4), and `strategy_stream_api_version()` (1) are unchanged.
128+
129+
Namespace versioning protects referenced internal C++ symbols; it does not
130+
validate an erased `pf_strategy_t` handle. Use a handle only with functions from
131+
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.
133+
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
137+
separate generic close request. The Pine component schema remains 1; it is
138+
independent of the aggregate fingerprint version. Prior v2 fingerprints are
139+
not comparable. Fingerprints are replay checks, not serialized checkpoints or
140+
complete hashes of private strategy state. The native runner already binds
141+
its strategy-library SHA; its ledger format and Python provenance fingerprints
142+
are separate contracts and do not change here.
143+
144+
Determinism is conditional on identical externally supplied market, intent and
145+
fill-report sequences, configuration, code and version. It is not a claim that
146+
live execution prices, quantities or callback arrival are predictable. The
147+
version bump changes linkage and fingerprint bytes; it changes no financial
148+
rule, fill price, fee, quota policy or economic test expectation.
130149

131150
If you find yourself reaching for any of these from outside the closed
132151
PineForge transpiler, you're holding it wrong — file an issue and we'll

‎docs/pages/fill-model.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,9 @@ that all hidden strategy state is equal.
105105

106106
The new receipt replaces protected C++ members and changes the fingerprint
107107
representation. Rebuild generated and native modules against matching headers
108-
and runtime. The internal class namespace and fingerprint domain are versioned;
109-
public C function signatures and POD layouts remain unchanged. See
108+
and runtime. The cap extraction advances the internal class namespace to
109+
`engine_script_run_v3`, broker hash domain to `pineforge-broker-state/v3`, and
110+
stream fingerprint prefix to 3. These pairing/serialization versions change
111+
no financial rule; public C signatures, POD layouts and API versions remain
112+
unchanged. See
110113
[ABI stability](abi-stability.md).

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

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Pine intraday cap: temporary engine-side compatibility
2+
3+
`compat::pine::IntradayCap` owns the active cap configuration, clock choice,
4+
quota/latch, close/reversal beneficiary, and close timing/price decisions.
5+
It lives temporarily under `include/pineforge/compat/pine/`. This checkpoint
6+
extracts those decisions from existing execution paths; it does not make the
7+
engine independent of Pine or establish broader TradingView parity.
8+
9+
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
13+
assign `max_intraday_filled_orders_ = (int)(expression)` at execution time;
14+
selecting a component does not evaluate or hoist a risk statement.
15+
16+
## Source facade and native scope
17+
18+
Default `BacktestEngine` construction uses `CapAttachment::None`. Merely
19+
supplying Pine cap metadata does not select the component, spend quota,
20+
create a close obligation or affect native fills. A native user can explicitly
21+
select Pine compatibility with `enable_pine_intraday_cap()` or an explicit
22+
`CapAttachment::LegacySource` constructor argument. This is a named frontend
23+
operation, not a generic native risk switch.
24+
25+
The protected name `max_intraday_filled_orders_` remains the **single
26+
`IntradayCap` value owner**, not an integer plus mirrored policy state.
27+
Assignment from `int` is an explicit legacy-source selection and preserves
28+
statement-time updates. It changes only the limit and attachment, retaining
29+
the quota, latch, continuation and other configuration. Positive, zero and
30+
negative assignments remain distinct. Value copying cannot alias another
31+
engine through an owner-bound proxy.
32+
33+
The one configuration object retains declared A/B/C metadata even when the
34+
component is unselected. It has no cap behavior until explicit selection.
35+
This preserves the cap interface used by older generated sources whose first
36+
risk statement occurs after host metadata: their protected assignment selects the
37+
component with the already-declared values. No second metadata buffer,
38+
configuration mirror or attachment-time replay exists. Repeated explicit
39+
selection is idempotent; it never renews quota or resets a pending action.
40+
41+
The actual base `set_syminfo_metadata` method, also used by the existing C ABI
42+
`strategy_set_syminfo_metadata`, forwards declarations to this owner. Only
43+
the compatibility component recognizes the three keys and their finite-
44+
positive rule. There is no derived setter shadow or new C export. New
45+
codegen selects before `strategy_create` returns, so the handler is already
46+
selected when the host sends metadata. Older cap assignments preserve prior
47+
declarations. Source that also assigns the removed `script_has_strategy_close_`
48+
member must be regenerated with the updated codegen before compiling.
49+
Rebuild C++ consumers against matching headers and archive after the layout
50+
change; public C signatures and POD layouts are unchanged.
51+
52+
This completes the default-construction boundary for this one component.
53+
The protected legacy source facade and physical engine-side compatibility
54+
package remain. Other Pine semantics elsewhere in the engine are not removed
55+
by this patch, and the three policy booleans are moved to their explicit owner,
56+
not claimed to have disappeared from the codebase.
57+
58+
## Preserved financial decisions
59+
60+
All independent A/B/C combinations retain their existing defaults and scope.
61+
No strategy name, winning-probe selector or alternate unused reducer is used.
62+
63+
* A filters only a same-direction MARKET attempt at live pyramiding capacity.
64+
Otherwise the established quota can charge a matched attempt before it has
65+
an economic effect. It is not a universal committed-execution count.
66+
* B selects next-ordinary-open timing only for the established historical
67+
POOC/same-bar MARKET shape. Default immediate fill/extreme prices and the
68+
existing COOF, magnifier and stream exclusions are preserved.
69+
* C counts the eligible committed full direct close and selects the earliest
70+
co-queued opposite MARKET incarnation. Its one-use quota transfer binds day,
71+
source bar and latest committed close sequence. The close and opposite entry
72+
remain separate broker events; FIFO row count is independent.
73+
74+
Positive limit activates quota enforcement. Existing shortcut guards that
75+
required exactly zero still distinguish a negative disabled limit from zero.
76+
Changing a limit does not renew quota; placement/admission on a new active
77+
risk day does. Explicit timed sessions use the existing unmerged exchange
78+
session clock; continuous/unconfigured sessions keep the existing chart-date
79+
fallback, including its omitted year. No other risk clock is changed.
80+
81+
## Engine intervention and lifetime
82+
83+
The policy accepts value records and returns typed admission and close
84+
decisions at the existing placement, pre-dispatch, committed-outcome and
85+
direct-close checkpoints. The engine dispatches the same order operations,
86+
callbacks and source-command batches. A synthetic close contributes its
87+
separate broker event but is not recursively charged to the cap.
88+
89+
`broker::PositionCloseObligation` contains only action identity, target
90+
position cycle, eligible boundary and comment. Pine charged day, slot count
91+
and trigger order stay in the policy's cause record. Quota renewal does not
92+
erase the generic obligation. Its next-open consumer checks the exact cycle
93+
and consumes the request once, after existing FX/open-margin handling and
94+
before resting orders and the script. A surviving partial position remains
95+
the target; a replacement cycle cannot inherit the request.
96+
97+
Taking a request does not prove flatness. The synchronous simulator attempts
98+
the existing close and observes its position/trade effects. This admission
99+
seam is **not** an external execution-ingestion API. A future broker adapter
100+
must accept already-observed executions regardless of submission limits and
101+
must establish request outcomes from actual execution/terminal observations.
102+
No such adapter or external-event replay protocol is introduced here.
103+
104+
Run reset clears the policy ledger/cause/action sequence and generic obligation
105+
while retaining attachment, limit and A/B/C settings. Value checkpoints copy
106+
both owners. Broker hashing includes compatibility schema version, selected
107+
attachment, configuration, every nested ledger/cause field, action sequence,
108+
and every generic request field/presence. Hash numbers therefore change across
109+
this source migration; nested coverage is checked without config waivers.
110+
111+
## Validation boundary
112+
113+
Local evidence is restricted to compilation and literal native/metadata tests,
114+
including the real C ABI transport and source-assignment shape. Corpus/Pine
115+
replays, local grading, TV exports and Cloud submission are excluded here.
116+
Independent Grok, unchanged fixed Cloud controls and full regression/gate
117+
verification remain root-owned requirements before any parity or publication
118+
claim.
119+
120+
## Internal pairing and observable-state version 3
121+
122+
Relative to base `38dc73e`, the new policy/obligation members change the
123+
`BacktestEngine` layout. Its inline namespace is now `engine_script_run_v3`;
124+
base-header v2 native/generated objects must fail to link against this runtime.
125+
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+
symbol stub is a reverse-link control, not a build of the entire old runtime.
128+
No mismatch test program is executed.
129+
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
132+
version1, POD layouts, exports and `PINEFORGE_HAS_SCRIPT_RUN_PREPARE_V1` remain
133+
unchanged. This version correction changes linking and serialized hash bytes,
134+
not cap charging, fill prices or other economic behavior. It does not make
135+
cross-module opaque C handles safe: retain the creating module's functions.
136+
137+
The generic design targets deterministic order actions given the same supplied
138+
market/intent/fill-report sequence, configuration and version. Observed
139+
executions remain distinct from admitted intents, committed source commands,
140+
callback cadence and report rows. A generic budget needs an explicit unit and
141+
owner; the current mixed attempt/full-close quota remains Pine compatibility.
142+
Pine close/reversal source batching, calculation cadence, session/chart risk
143+
clock and A/B/C selection stay with the explicit compatibility component.
144+
The physical package and legacy source facade remain migration work; these
145+
are not generic-core switches.
146+
147+
MetaTrader provides a useful independent model: a successful send is not proof
148+
of execution, and one request can produce multiple transaction notifications.
149+
The transaction arrival order is not guaranteed. Those constraints support
150+
separating requests, execution facts and exposure state; they do not establish
151+
Pine quota policy or predictable live fills. See [MQL5 OrderSend](https://www.mql5.com/en/docs/trading/ordersend)
152+
and [OnTradeTransaction](https://www.mql5.com/en/docs/event_handlers/ontradetransaction).
153+
This patch adds no external execution adapter or callback-ordering model.

0 commit comments

Comments
 (0)