Skip to content

Commit d5a5eaf

Browse files
committed
Align lifecycle and admission documentation with final v11 model
1 parent e6bfb37 commit d5a5eaf

6 files changed

Lines changed: 41 additions & 31 deletions

File tree

‎docs/pages/abi-stability.md‎

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -112,20 +112,22 @@ 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. Deriving the two placement facts from their original admission
116-
observation changes the native layout and advances `PendingOrder` and
117-
`BacktestEngine` to `engine_script_run_v10`. Exact pre-change f2df706/v9
115+
runtime. Deriving placement and opposite-predecessor facts from original
116+
admission evidence changes the native layout and advances `PendingOrder` and
117+
`BacktestEngine` to `engine_script_run_v11`. Exact pre-change fd4c686/v10
118118
headers are authenticated before native, generated-style and standalone
119119
PendingOrder pairing checks. Current/old matching links must succeed and stale
120-
pairings must fail for the expected qualified symbols. Earlier v2-v8 controls
120+
pairings must fail for the expected qualified symbols. Earlier v2-v9 controls
121121
remain; every translation unit must compile before any mismatch is accepted.
122122
No pairing executable runs.
123123

124124
New standalone lifecycle values and `Lifecycle` own the inline namespace
125125
`pineforge::exit_legs::lifecycle_v1`; new admission values, `Draft`, `Journal`
126-
and capture classes/methods own `pineforge::admission::market_admission_v1`.
127-
Cancellation values retain `pineforge::order_cancellation_v1`; none of these
128-
standalone representations changes in the placement derivation.
126+
and capture classes/methods own `pineforge::admission::market_admission_v2`.
127+
The admission epoch changes because prior-book observations now capture each
128+
instruction's raw buy/sell direction. Authenticated v1 headers have separate
129+
matching and stale-link controls. Cancellation values retain
130+
`pineforge::order_cancellation_v1`.
129131
Header-only lifecycle methods do not require a library reference by themselves;
130132
separate caller/provider argument controls verify cross-translation-unit type
131133
identity. Admission method controls also link the current runtime archive.
@@ -145,7 +147,7 @@ module to obtain complete script-state reset; replacing an archive does not
145147
retrofit an old module. Public C function signatures, `PF_ABI_VERSION` (4),
146148
and `strategy_stream_api_version()` (1) are unchanged. The pending-order v1
147149
mirror preserves all 406 pre-change field names/types/offsets and its full
148-
3192-byte size. No field is added for the placement derivation: the original
150+
3192-byte size. No field is added for these placement derivations: the original
149151
admission operands already have actual-value projections, while removed native
150152
booleans survive as derived legacy outputs. Compiler static assertions compare
151153
every field with the authenticated v9 mirror. Size-limited reads keep old callers
@@ -154,16 +156,16 @@ within their buffers.
154156
Namespace versioning protects referenced internal C++ symbols; it does not
155157
validate an erased `pf_strategy_t` handle. Use a handle only with functions from
156158
its creating strategy module. A fully self-contained old module can still use
157-
its own matching runtime; this check does not turn it into a v10 module.
159+
its own matching runtime; this check does not turn it into a v11 module.
158160

159161
The integrated representation advances the broker fingerprint domain to
160-
`pineforge-broker-state/v10` and stream fingerprint version to 10. The original
161-
admission observation is hashed once; its two derived placement views no longer
162-
add redundant folds. Lifecycle definitions, generations, obligations and replay
162+
`pineforge-broker-state/v11` and stream fingerprint version to 11. The original
163+
admission observation and prior-book direction are hashed as canonical facts;
164+
the three derived placement views add no redundant folds. Lifecycle definitions, generations, obligations and replay
163165
receipts, plus causal journal state remain represented. Existing
164166
reservation, Pine instruction, activation, quantity, predecessor and birth facts
165167
remain represented. The Pine component schema remains 1; it is
166-
independent of the aggregate fingerprint version. Prior v2-v9 fingerprints are
168+
independent of the aggregate fingerprint version. Prior v2-v10 fingerprints are
167169
not comparable. Fingerprints are replay checks, not serialized checkpoints or
168170
complete hashes of private strategy state. The native runner already binds
169171
its strategy-library SHA; its ledger format and Python provenance fingerprints

‎docs/pages/exit-leg-lifecycle.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,8 @@ All nested definition, generation, cause, obligation, window and latest-receipt
7474
facts are reflected/hashed once from canonical state. Legacy D/R/T/O/H/K/B/B0
7575
fields are read-only projections. This model removes three stored booleans.
7676
Admission, cancellation and placement-fact consolidation have reduced the
77-
direct PendingOrder boolean census from 17 to 6; this includes two ordinary
77+
direct PendingOrder boolean census from 17 to 5; the opposite-predecessor
78+
result is now derived from the accepted command journal. The five include two ordinary
7879
direction/activation facts and does not count every engine policy option.
7980
Optional obligations, three leg generations,
8081
retirement receipts, immutable definition references and action/domain variants

‎docs/pages/market-admission.md‎

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ An actual margin fill can revise resolved sizing without changing the original
2222
observation. Original opening qualification is also distinct from the later
2323
broker `OpeningReceipt` Check/Exempt decision, which belongs to a committed fill.
2424

25-
Two historical placement views now derive from these same original facts:
25+
Three historical placement views now derive from original admission evidence:
2626

2727
- `placement_has_prior_close(order)` compares the original accepted-close
2828
quantity with the existing quantity tolerance. This describes a source-time
@@ -31,14 +31,24 @@ Two historical placement views now derive from these same original facts:
3131
- `placement_at_entry_capacity(order)` compares original placement side,
3232
requested direction and held-entry count with the original configured cap.
3333
Later fills, cancellation, sizing revisions or cap changes cannot alter it.
34+
- `placement_has_opposite_market_predecessor(journal, order)` finds the order's
35+
accepted command event and examines its original physical book, excluding
36+
incarnations that the command removed. Earlier opposite MARKET instructions
37+
on the same source bar count even if later canceled or removed. A canceled
38+
peer that was still physically resident at placement also counts.
3439

35-
These views remove two independently writable copies of already stored facts.
36-
No replacement mask, enum profile or extra state is introduced. A manual order
40+
The first two views remove independently writable copies of already stored
41+
facts. The third removes a stored result and adds `BookObservation.buy`, the
42+
raw instruction direction captured from every physical peer. Held position side
43+
cannot supply this fact, especially for flat-born or manually constructed
44+
MARKET peers. No predecessor-result cache, mask or profile is retained. A manual order
3745
without an original admission observation retains the historical false default.
3846
Native callers that construct orders directly must supply their real original
3947
observation when these placement facts matter; a later executable quantity or
4048
position snapshot is not a substitute. The legacy C mirror columns remain at
4149
their original offsets as derived outputs, alongside the original observation.
50+
The predecessor view additionally requires the matching accepted command event
51+
in the owning journal; a standalone observation does not establish that history.
4252

4353
## Causal receipts
4454

@@ -69,6 +79,11 @@ observation for each live command: N simultaneous resting orders can retain
6979
N(N-1)/2 prior-book rows. This cost still needs a separate representation change;
7080
the journal is not a fixed-memory or durable venue-event store.
7181

82+
The C pending-order accessor supplies the owning journal to derive the
83+
predecessor column without changing its offset. A context-free internal mirror
84+
call refuses a bound flat-born priced entry before writing output; it cannot
85+
invent a false result when the required history was not supplied.
86+
7287
These identities belong to one engine run. Reset begins a new run; callers must
7388
not submit persisted receipts from a different engine or run. External broker
7489
reconciliation requires a separate durable identity contract.

‎include/pineforge/engine.hpp‎

Lines changed: 6 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -513,18 +513,12 @@ struct PendingOrder {
513513
// close(id) fill cannot impersonate close_all. -1/0 means no provenance.
514514
int same_id_stop_deferred_close_all_bar = -1;
515515
uint64_t same_id_stop_deferred_close_all_incarnation = 0;
516-
// KI-65 dual same-bar opposite entry (probe pf-probe-ki65-dual-entry-
517-
// precedence): true when this priced (stop/limit) ENTRY was placed from
518-
// FLAT and an EARLIER same-on_bar OPPOSITE-direction MARKET entry is
519-
// pending. TV runs no arbitration on two opposite same-bar strategy.entry
520-
// calls — BOTH execute; the second call's sizing freezes at placement as
521-
// own + the pending opposite MARKET qty (a pending STOP contributes 0 — the
522-
// SS cells stay single-close; a placement-rejected market never reaches the
523-
// pending queue, so it contributes 0 too). When set, apply_entry_order_fill
524-
// scopes the M2a close_only_opposite gate OUT so this leg FULLY REVERSES the
525-
// position the market leg opened (flip_market_position_to) instead of
526-
// collapsing to close-only-flat. Scoped to created-FLAT so the deferred-flip
527-
// carry (created OPPOSITE) is untouched.
516+
// KI-65 priced-entry precedence uses the derived
517+
// placement_has_opposite_market_predecessor journal query. An accepted
518+
// flat-born priced ENTRY retains full reversal when its original book
519+
// contained an earlier opposite MARKET on the same source bar. Removed
520+
// same-id predecessors and placement-rejected calls do not contribute.
521+
// No independently writable predecessor result is stored on the order.
528522
// KI-65 MARKET/MARKET follow-up candidate. Every own-affordable explicit
529523
// MARKET call in the pinned broker scope carries this snapshot until the
530524
// next broker-processing boundary, where the complete source-bar set is
Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
11
# Frozen engine_script_run_v8 header closure
22

33
This fixture is the exact tracked header closure from `79921099a9357cb5bbace907a9319479f6640d89` (tree `e141657c572b4a3855dfee607f9951e331b961e6`). It is used only by the compile and link controls in `scripts/check_script_cpp_abi.py` to prove that the pre-cancellation v8 native/generated surface is rejected by the current v9 engine symbols. No strategy, executable, feed, or reference engine is run.
4-

‎tests/fixtures/script_cpp_abi/basev9/README.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,3 @@ This fixture is the exact recursive tracked header closure from
66
compile and link controls to prove that the pre-placement-derivation v9
77
native/generated surface is rejected by the v10 runtime. No strategy,
88
executable, feed, or reference engine is run.
9-

0 commit comments

Comments
 (0)