|
| 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