Implement deterministic realtime execution contract

[luisleo526]

Summary

• define and implement PineForge's deterministic close-only historical-to-realtime execution contract
• reject unsupported every-tick, every-history-tick, and order-fill-recalculation profiles before warmup
• separate trade events from clock/bar-close events; add fixed-grid and data-driven gap policies
• prevent quiet clock events from filling orders, ratcheting trails, updating excursions, or triggering price-based margin actions
• preserve actual last-trade timestamp/sequence for process-on-close fills
• persist realtime stop-limit activation and keep realtime trailing state per executable order
• introduce immutable command-revision, order-leg, fill, entry-lot, and position-episode identities
• add ABI v3 structured lifecycle diagnostics with canonical count/hash, overflow accounting, Python mirrors, docs, and tutorial output
• use exact order-leg identity for realtime OCA exclusion while preserving the historical kernel
• expand corpus scoring with price/P&L distributions, lifecycle hashes, and first-divergence context
• add a manual TradingView P1-P9 realtime probe kit with scheduled arming, JSON-only traces/fills, pre-registered decisions, complete capture manifests, and artifact validation

Why

The existing stream path preserved one strategy instance but silently mixed clock events with executable prices, lost stop-limit activation between trades, shared one trailing watermark across exits, and exposed no deterministic broker lifecycle. This made realtime behavior difficult to audit and unsafe as a later alert/webhook source.

The contract is PineForge's deterministic simulator contract. It uses TradingView documentation as the Pine semantics reference but does not claim to clone TradingView's private realtime feed or executor.

Validation

• CMake Release build with tests and corpus strategies enabled
• ctest --test-dir build --output-on-failure: 89/89 passed
• python3 scripts/check_c_abi_runtime.py: passed
• ./scripts/run_corpus.sh: 252/252, zero failures; 240 excellent, 11 strong, 1 existing anomaly
• streaming tutorial: passed and emitted lifecycle identities/hash
• all 9 TradingView Pine v6 probe sources pass the local PineForge parser/analyzer
• the capture validator passes a synthetic complete-run fixture and verifies source/artifact hashes, receipt/body correspondence, scheduled arming, and JSON schemas
• three whole-session corpus handoffs through exclusive 2025-05-01T00:00:00Z: 756/756 runtime success, exact input/script bar counts
  • 2025-02-07 03:17: 241/252 exact trade count, 228/252 fully structural, 99.0363% weighted ordered match
  • 2025-03-11 14:23: 242/252 exact trade count, 234/252 fully structural, 99.3784% weighted ordered match
  • 2025-03-29 22:41: 243/252 exact trade count, 235/252 fully structural, 99.5667% weighted ordered match

See docs/realtime-contract-3-session-report.md for the score definitions and price/P&L distributions.

Scope still open

This remains a draft. The P1-P9 probe sources and collection protocol are ready, but the manual TradingView observations/results are still pending. The revised completion gate also requires full per-entry-lot exit fan-out, a canonical whole-engine handoff digest, a frozen same-scorer pre-change run, and a second deterministic execution of all 756 sessions. Alert/webhook transport and JSON delivery inside PineForge remain intentionally out of scope; lifecycle fill_id is the idempotency source for that later layer.