Skip to content

Commit 149f77c

Browse files
committed
Replace seven pending-order flags with quantity and event facts
Track quantity requests and reservation bases, exact replacement predecessors, and callback birth/cursor provenance instead of independent Boolean labels. Capture resolved targets for deferred closes before later reservation binding. Keep the remaining Pine historical reach permission explicit. Preserve the v1 C mirror prefix with derived legacy outputs and appended facts. Version PendingOrder and BacktestEngine together to reject stale C++ objects.
1 parent c45cf5a commit 149f77c

43 files changed

Lines changed: 2801 additions & 351 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎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_birth.cpp
8182
src/compat/pine/order_priority.cpp
8283
src/engine_aux_security.cpp
8384
src/engine_fills.cpp

‎docs/pages/abi-stability.md‎

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -112,30 +112,32 @@ 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 and priority extractions change the v2/v3 object layouts and
116-
therefore use the internal `engine_script_run_v4` inline namespace. An object
117-
built from base `38dc73e` headers references v2 out-of-line members and must
118-
fail to link to this v4 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. Frozen f864/v3 headers are also rejected by this v4 runtime. Both generated-style
121-
and native-style current callers must still link.
115+
runtime. The integrated quantity, predecessor and order-birth representation
116+
changes `PendingOrder` and uses internal `engine_script_run_v5`. Exact frozen
117+
c45/v4 headers are compiled before link tests: both native and generated-style
118+
v4 callers must fail to link to the v5 archive, while matched v5 callers link.
119+
Earlier exact base38/v2 and f864/v3 mismatch controls remain. A compile failure
120+
cannot masquerade as mismatch protection; no pairing executable is run.
122121

123122
`PINEFORGE_HAS_SCRIPT_RUN_PREPARE_V1` remains 1: it describes the existing hook
124123
capability, not the class layout version. Regenerate and rebuild a strategy
125124
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.
125+
retrofit an old module. Public C function signatures, `PF_ABI_VERSION` (4),
126+
and `strategy_stream_api_version()` (1) are unchanged. The pending-order v1
127+
mirror keeps all 108 existing field names/types/offsets and its full old prefix;
128+
new typed facts append, and removed native booleans survive only as read-only
129+
derived outputs. Size-limited reads keep old callers within their buffers.
128130

129131
Namespace versioning protects referenced internal C++ symbols; it does not
130132
validate an erased `pf_strategy_t` handle. Use a handle only with functions from
131133
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 v4 module.
134+
its own matching runtime; this check does not turn it into a v5 module.
133135

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
137-
separate generic close request. The Pine component schema remains 1; it is
138-
independent of the aggregate fingerprint version. Prior v2/v3 fingerprints are
136+
The integrated representation advances the broker fingerprint domain to
137+
`pineforge-broker-state/v5` and stream fingerprint version to 5. These identify
138+
changed serialized quantity/reservation, predecessor and birth facts, alongside
139+
existing Pine policy state. The Pine component schema remains 1; it is
140+
independent of the aggregate fingerprint version. Prior v2/v3/v4 fingerprints are
139141
not comparable. Fingerprints are replay checks, not serialized checkpoints or
140142
complete hashes of private strategy state. The native runner already binds
141143
its strategy-library SHA; its ledger format and Python provenance fingerprints

‎docs/pages/quantity-intent.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
`PendingOrder::quantity_request` separates an exit's original requested amount
2+
from the numeric reservation made for that request. It replaces two stored
3+
booleans that mixed those lifetimes.
4+
5+
`QuantityIntent` contains exactly one of `Units(amount)`,
6+
`Fraction(numerator, denominator)` or `All`. Fractional requests retain their
7+
original representation; the Pine boundary supplies percentages as `P / 100`
8+
without a floating-point divide/multiply round trip. An absent request belongs
9+
to pending commands outside this exit-request contract. These are request
10+
descriptors, not an additional numerical-admission policy.
11+
12+
`QuantityReservation` records admitted units and the exposure basis used when
13+
reserving them. A new request clears the old reservation; a reservation cannot
14+
exist without an original request. Deferred exits acquire this receipt when a
15+
live owner is bound. Additional per-entry bindings copy the original request
16+
and record their own admitted amount and basis. Copying is by value.
17+
18+
`qty` and `qty_percent` retain their current executable/reserved meaning in the
19+
existing order paths. OCA can reduce executable quantity without changing
20+
the original intent or its prior reservation receipt. Whether that receipt
21+
covered less than its basis is a derived numerical comparison, using the
22+
existing caller-supplied tolerances. A deferred fraction can be classified
23+
before resolution; an unbound Units request cannot infer coverage without a
24+
numeric basis.
25+
26+
Consequently, a half-position request rounded to a minimum one-unit slot may
27+
have `Fraction(50, 100)` intent and a full `1 / 1` reservation. Conversely an
28+
`All` request clipped behind another reservation may hold only `3 / 4` of its
29+
basis. Neither case can be represented correctly by one “partial” label.
30+
31+
Deferred market-close instructions are another producer: `strategy.close`
32+
has already resolved its source amount to a placement target before
33+
`queue_deferred_close_order` runs. The request records that resolved source
34+
target as `Units(qty_to_close)`, without an exposure reservation until a later
35+
layered binding occurs. This is not a fixed executable-quantity promise: the
36+
preserved Pine ANY-relative rule can turn target 1 on E2 into reservation 2
37+
with basis E4 after reversal. The initial target remains 1 while executable
38+
`qty` and the later reservation are 2. It does not claim to retain the original
39+
Pine percentage expression; that conversion already occurred. This preserves
40+
the old initial nonpartial classification without fabricating a basis.
41+
42+
The Pine percentage rounding, minimum-slot, reservation retention, one-shot
43+
exit-ID and deferred/replacement policies remain explicit compatibility debt
44+
in their existing callers. This change does not generalize those policies or
45+
change their thresholds, financial assertions or execution order.
46+
47+
The public `pf_pending_order_v1_t` retains its complete existing field prefix.
48+
Its `requested_partial` and `full_percent_exit_request` fields are deprecated
49+
read-only projections derived from the new authoritative values; native
50+
decisions never read those output fields. New fields append:
51+
52+
- `quantity_intent_kind`: 0 absent, 1 Units, 2 Fraction, 3 All.
53+
- The relevant units or fraction numerator/denominator; inactive values are 0.
54+
- Reservation presence, admitted units and basis units.
55+
56+
All new facts and optional-presence discriminators participate in broker
57+
hashing and mirror output. They are not waived. C ABI version 4 and stream
58+
API version 1 remain unchanged, and size-limited mirror reads preserve older
59+
callers. The internal C++ layout changes, so all consumers require a matching
60+
rebuild and the integrated representation change requires a new internal
61+
namespace/fingerprint epoch before publication.

‎docs/pending-placement-receipts.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Pending-order placement and replacement facts
2+
3+
`PendingOrder::replaced_order_incarnation` identifies the immediate live
4+
predecessor whose priority slot the newly accepted order retains. Zero means
5+
fresh construction. The new order still receives its own fresh `incarnation`;
6+
`created_seq` remains its scheduling priority, not identity.
7+
8+
The receipt is populated by high-level MARKET/ENTRY, RAW, and primary EXIT
9+
replacement. Named cancel followed by recreation is fresh; its separate
10+
cancel/recreate receipt does not become a replacement. When a Pine exit
11+
reissue materializes multiple legs, the primary leg inherits the preceding
12+
primary's priority and predecessor; additional legs are fresh. This receipt
13+
does not claim to enumerate all sibling objects erased by that reissue.
14+
15+
The former native `created_by_same_id_replacement` Boolean and redundant
16+
`replaced_exit_order_incarnation` scalar are removed. Replacement readers use
17+
the authoritative predecessor. The conditional
18+
`replaced_default_market_incarnation` remains a Pine qualification receipt:
19+
it records additional predecessor kind, sizing, side, source-bar and cycle
20+
conditions that generic replacement identity alone cannot establish later.
21+
22+
The former `created_while_in_position` Boolean is also removed. Its production
23+
meaning was EXIT-only: `strategy.exit` derived it from the same `effectively_flat`
24+
calculation used for `created_position_side`; a positive deferred close used the
25+
nonflat side it targeted. EXIT consumers now read that existing placement side.
26+
The two non-EXIT checks were vacuous because their producers always left the
27+
old Boolean false; those checks are removed without requiring flat placement.
28+
29+
`created_position_side` is not renamed or reinterpreted as a universal physical
30+
snapshot. MARKET/ENTRY/RAW capture physical exposure; a Pine EXIT captures
31+
exposure after earlier same-evaluation close claims. The physical position can
32+
still be open when such an EXIT captures FLAT. Existing cycle/carry fields and
33+
their scopes are unchanged. A complete physical placement/close-claim model is
34+
separate work.
35+
36+
The public size-aware `pf_pending_order_v1_t` retains every existing field at
37+
its original offset. Its old replacement Boolean, EXIT predecessor scalar and
38+
in-position Boolean are deprecated derived **output projections**, never core
39+
state or inputs. The legacy RAW projections remain false/zero; the appended
40+
`replaced_order_incarnation` reports the true RAW predecessor. Dynamic-layout
41+
readers can discover the new field; older prefix readers retain their layout.
42+
The generator emits these projections explicitly without native storage or a
43+
readback path. Native hashing includes the predecessor once and placement side
44+
once; removed redundant fields need no independent hash state.
45+
46+
This removes two of the 32 direct PendingOrder Boolean members, leaving 30 in
47+
this component. It replaces one bit with factual identity and removes one
48+
duplicate placement value; it is not a Boolean wrapper or a renamed policy
49+
mask. Existing Pine priority/admission/close policies still read these facts
50+
and retain their existing qualification rules. Public C ABI version 4 and
51+
pending mirror version 1 remain unchanged. Final aggregate internal C++/hash
52+
versioning and stale-object pairing are owned by the integrated refactor;
53+
this component must not be published separately without that boundary.
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
#pragma once
2+
#include "../../order_birth.hpp"
3+
4+
namespace pineforge { inline namespace engine_script_run_v5 { struct PendingOrder; } }
5+
namespace pineforge::compat::pine {
6+
7+
// Historical Pine permissions remain policy, not physical birth facts.
8+
enum class HistoricalBirthReach : int32_t { Standard, ExtremeWaypoints };
9+
inline bool first_open_fill_evaluation(const OrderBirth& birth) {
10+
return birth.from_fill() && birth.evaluation_ordinal() == 1
11+
&& birth.cursor().first_point();
12+
}
13+
HistoricalBirthReach select_historical_birth_reach(const OrderBirth& birth,
14+
bool requested_trailing_exit);
15+
bool historical_cascade_reach(const PendingOrder& order);
16+
17+
} // namespace pineforge::compat::pine
18+
19+
namespace pineforge {
20+
using PineHistoricalBirthReach = compat::pine::HistoricalBirthReach;
21+
}

‎include/pineforge/compat/pine/order_priority.hpp‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
#include <string>
66
#include <vector>
77

8-
namespace pineforge { struct PendingOrder; }
8+
namespace pineforge { inline namespace engine_script_run_v5 { struct PendingOrder; } }
99
namespace pineforge::compat::pine {
1010

1111
struct OrderPriorityContext {

0 commit comments

Comments
 (0)