fix: wait for aligned perp mark bars in paper sessions

Author: journeytosilius

README.md

@@ -150,7 +150,9 @@ when the session never produced a first snapshot. The bundled
 the canonical multi-source strategy and the trigger-happy smoke test run side
 by side. The paper daemon keeps the last closed candle armed when an exchange
 temporarily returns no fresh bar for the current live append window, then
-resumes once the next closed candle appears.
+resumes once the next closed candle appears. Perp sessions now also wait for
+aligned mark-price candles instead of failing immediately when the venue lags
+the execution feed by one runtime window.
 
 The CLI, IDE server, and LSP now also emit structured JSON logs on `stderr`.
 Set `PALMSCRIPT_LOG_LEVEL=debug` or `trace` when you need more detail, and set

crates/palmscript/src/execution/engine.rs

@@ -1,4 +1,6 @@
-use crate::backtest::{BacktestConfig, PerpBacktestConfig, PerpBacktestContext, PerpMarginMode};
+use crate::backtest::{
+    BacktestConfig, BacktestError, PerpBacktestConfig, PerpBacktestContext, PerpMarginMode,
+};
 use crate::compiler::compile;
 use crate::run_backtest_with_sources;
 use crate::runtime::VmLimits;
@@ -264,8 +266,7 @@ pub(crate) async fn process_paper_session(
             perp_context: session.perp_context.clone(),
             portfolio_perp_contexts: session.portfolio_perp_contexts.clone(),
         },
-    )
-    .map_err(|err| ExecutionError::Runtime(err.to_string()));
+    );
 
     match result {
         Ok(result) => {
@@ -323,7 +324,11 @@ pub(crate) async fn process_paper_session(
             );
             Ok(manifest)
         }
+        Err(BacktestError::MissingPerpMarkFeed { alias }) => {
+            defer_perp_mark_alignment(session, &mut manifest, runtime_to_ms, &alias)
+        }
         Err(err) => {
+            let err = ExecutionError::Runtime(err.to_string());
             manifest.status = ExecutionSessionStatus::Failed;
             manifest.health = ExecutionSessionHealth::Failed;
             manifest.updated_at_ms = now_ms;
@@ -361,6 +366,36 @@ pub(crate) async fn process_paper_session(
     }
 }
 
+fn defer_perp_mark_alignment(
+    session: &mut LoadedPaperSession,
+    manifest: &mut PaperSessionManifest,
+    runtime_to_ms: i64,
+    alias: &str,
+) -> Result<PaperSessionManifest, ExecutionError> {
+    session.perp_context_to_ms = session
+        .perp_context_to_ms
+        .min(runtime_to_ms.saturating_sub(1));
+    let message =
+        format!("paper session waiting for aligned perp mark bars for execution `{alias}`");
+    update_manifest_status(
+        manifest,
+        ExecutionSessionStatus::ArmingLive,
+        ExecutionSessionHealth::WarmingUp,
+        None,
+        &message,
+    )?;
+    warn_fields(
+        "paper.session.waiting_perp_mark_bars",
+        "Paper session waiting for aligned perp mark bars",
+        vec![
+            LogField::string("session_id", manifest.session_id.clone()),
+            LogField::string("execution_alias", alias.to_string()),
+            LogField::i64("runtime_to_ms", runtime_to_ms),
+        ],
+    );
+    Ok(manifest.clone())
+}
+
 fn infer_health(feed_snapshots: &[super::PaperFeedSnapshot]) -> ExecutionSessionHealth {
     if feed_snapshots.is_empty() {
         return ExecutionSessionHealth::Live;
@@ -445,7 +480,7 @@ fn update_manifest_status(
 
 #[cfg(test)]
 mod tests {
-    use super::LoadedPaperSession;
+    use super::{defer_perp_mark_alignment, LoadedPaperSession};
     use crate::backtest::{DiagnosticsDetailMode, PerpMarginMode};
     use crate::compile;
     use crate::exchange::ExchangeEndpoints;
@@ -458,6 +493,8 @@ mod tests {
     use crate::runtime::VmLimits;
     use mockito::{Matcher, Server};
     use serde_json::json;
+    use std::collections::BTreeMap;
+    use std::path::PathBuf;
 
     fn sample_manifest(endpoints: ExchangeEndpoints) -> PaperSessionManifest {
         PaperSessionManifest {
@@ -611,4 +648,50 @@ plot(perp.close)";
         assert_eq!(refreshed.mark_bars[2].time as i64, 1_704_074_400_000);
         assert_eq!(session.perp_context_to_ms, 1_704_078_000_000);
     }
+
+    #[test]
+    fn defer_perp_mark_alignment_keeps_session_warming_and_retries_window() {
+        let state_dir = tempfile::tempdir().expect("tempdir");
+        std::env::set_var("PALMSCRIPT_EXECUTION_STATE_DIR", state_dir.path());
+
+        let compiled = compile(
+            "interval 1m
+source perp = binance.usdm(\"BTCUSDT\")
+execution exec = binance.usdm(\"BTCUSDT\")
+plot(perp.close)",
+        )
+        .expect("compile");
+        let manifest = sample_manifest(ExchangeEndpoints::default());
+        let feed_plan = build_session_feed_plan(
+            &compiled,
+            &manifest.config.execution_source_aliases,
+            manifest.start_time_ms,
+            &manifest.endpoints,
+        )
+        .expect("feed plan");
+        let mut session = LoadedPaperSession {
+            compiled,
+            feed_plan,
+            perp: None,
+            perp_context: None,
+            portfolio_perp_contexts: BTreeMap::new(),
+            perp_context_to_ms: 1_704_067_500_000,
+        };
+        let mut manifest = PaperSessionManifest {
+            session_id: "paper-wait".to_string(),
+            script_path: Some(PathBuf::from("strategy.ps").display().to_string()),
+            ..manifest
+        };
+
+        let deferred =
+            defer_perp_mark_alignment(&mut session, &mut manifest, 1_704_067_500_000, "exec")
+                .expect("defer should succeed");
+
+        assert_eq!(deferred.status, ExecutionSessionStatus::ArmingLive);
+        assert_eq!(deferred.health, ExecutionSessionHealth::WarmingUp);
+        assert_eq!(deferred.failure_message, None);
+        assert_eq!(session.perp_context_to_ms, 1_704_067_499_999);
+
+        std::env::remove_var("PALMSCRIPT_EXECUTION_STATE_DIR");
+    }
 }

crates/palmscript/tests/execution.rs

@@ -5,7 +5,8 @@ use mockito::{Matcher, Server};
 use palmscript::{
     load_paper_session_export, load_paper_session_logs, serve_execution_daemon, stop_paper_session,
     submit_paper_session, DiagnosticsDetailMode, ExchangeEndpoints, ExecutionDaemonConfig,
-    ExecutionSessionStatus, PaperSessionConfig, SubmitPaperSession, VmLimits,
+    ExecutionSessionHealth, ExecutionSessionStatus, PaperSessionConfig, SubmitPaperSession,
+    VmLimits,
 };
 
 static ENV_LOCK: Mutex<()> = Mutex::new(());
@@ -413,6 +414,81 @@ fn paper_daemon_processes_a_perp_session_without_async_blocking_panics() {
     std::env::remove_var("PALMSCRIPT_BINANCE_USDM_BASE_URL");
 }
 
+#[test]
+fn paper_daemon_waits_for_aligned_perp_mark_bars_instead_of_failing_session() {
+    let _guard = ENV_LOCK.lock().expect("lock env");
+    let state_dir = tempfile::tempdir().expect("tempdir");
+    let mut server = Server::new();
+    mock_binance_usdm_interval(
+        &mut server,
+        "1m",
+        &[
+            serde_json::json!([1704067200000_i64, "10", "10", "10", "10", "1000"]),
+            serde_json::json!([1704067260000_i64, "11", "11", "11", "11", "1000"]),
+            serde_json::json!([1704067320000_i64, "12", "12", "12", "12", "1000"]),
+            serde_json::json!([1704067380000_i64, "13", "13", "13", "13", "1000"]),
+        ],
+    );
+    mock_binance_usdm_mark_interval(
+        &mut server,
+        "1m",
+        &[
+            serde_json::json!([1704067200000_i64, "10", "10", "10", "10", "0"]),
+            serde_json::json!([1704067260000_i64, "11", "11", "11", "11", "0"]),
+            serde_json::json!([1704067320000_i64, "12", "12", "12", "12", "0"]),
+        ],
+    );
+    mock_binance_usdm_exchange_info(&mut server);
+    mock_binance_usdm_book_ticker(&mut server);
+    mock_binance_usdm_last_price(&mut server);
+    mock_binance_usdm_premium_index(&mut server);
+
+    std::env::set_var("PALMSCRIPT_EXECUTION_STATE_DIR", state_dir.path());
+    std::env::set_var("PALMSCRIPT_BINANCE_USDM_BASE_URL", server.url());
+
+    let manifest = submit_paper_session(SubmitPaperSession {
+        source: perp_source().to_string(),
+        script_path: Some(PathBuf::from("perp_strategy.ps")),
+        config: PaperSessionConfig {
+            execution_source_aliases: vec!["exec".to_string()],
+            initial_capital: 1_000.0,
+            maker_fee_bps: 0.0,
+            taker_fee_bps: 0.0,
+            execution_fee_schedules: std::collections::BTreeMap::new(),
+            slippage_bps: 0.0,
+            diagnostics_detail: DiagnosticsDetailMode::SummaryOnly,
+            leverage: Some(5.0),
+            margin_mode: Some(palmscript::PerpMarginMode::Isolated),
+            vm_limits: VmLimits::default(),
+        },
+        start_time_ms: 1704067320000_i64,
+        endpoints: ExchangeEndpoints::from_env(),
+    })
+    .expect("perp paper session submission should succeed");
+
+    let status = serve_execution_daemon(ExecutionDaemonConfig {
+        poll_interval_ms: 1,
+        once: true,
+    })
+    .expect("daemon should wait for aligned perp mark bars");
+    assert!(!status.running);
+
+    let export = load_paper_session_export(&manifest.session_id).expect("perp paper export");
+    let logs = load_paper_session_logs(&manifest.session_id).expect("paper logs should load");
+    assert_eq!(export.manifest.status, ExecutionSessionStatus::ArmingLive);
+    assert_eq!(export.manifest.health, ExecutionSessionHealth::WarmingUp);
+    assert_eq!(export.manifest.failure_message, None);
+    assert!(export.latest_result.is_none());
+    assert!(
+        logs.iter()
+            .any(|event| event.message.contains("waiting for aligned perp mark bars")),
+        "{logs:#?}"
+    );
+
+    std::env::remove_var("PALMSCRIPT_EXECUTION_STATE_DIR");
+    std::env::remove_var("PALMSCRIPT_BINANCE_USDM_BASE_URL");
+}
+
 #[test]
 fn paper_daemon_keeps_binance_usdm_session_live_when_funding_feed_is_empty() {
     let _guard = ENV_LOCK.lock().expect("lock env");

web/docs/docs/tooling/cli.de.md

@@ -162,7 +162,7 @@ The v1 execution layer is intentionally conservative:
 - one persistent local ledger per paper session
 - the same strategy semantics, portfolio caps, cooldowns, and max-bars exits as backtest mode
 
-When you submit a paper session, PalmScript snapshots the script and queues a persistent session locally. `execution serve` warms the VM with compiler-derived pre-session history, keeps one shared armed feed cache for the active paper sessions, and updates the strategy only when a new execution candle closes. Sessions remain in explicit `arming_history` and `arming_live` states until the required feed inventory is ready. If an exchange temporarily returns no fresh bar for the current live append window, the daemon keeps the last closed candle armed and resumes on the next closed candle instead of failing the session.
+When you submit a paper session, PalmScript snapshots the script and queues a persistent session locally. `execution serve` warms the VM with compiler-derived pre-session history, keeps one shared armed feed cache for the active paper sessions, and updates the strategy only when a new execution candle closes. Sessions remain in explicit `arming_history` and `arming_live` states until the required feed inventory is ready. If an exchange temporarily returns no fresh bar for the current live append window, the daemon keeps the last closed candle armed and resumes on the next closed candle instead of failing the session. Perp sessions also stay in `arming_live` and retry when mark-price candles have not caught up to the execution window yet.
 
 The shared quote layer currently provides, per execution alias:
 

web/docs/docs/tooling/cli.es.md

@@ -162,7 +162,7 @@ The v1 execution layer is intentionally conservative:
 - one persistent local ledger per paper session
 - the same strategy semantics, portfolio caps, cooldowns, and max-bars exits as backtest mode
 
-When you submit a paper session, PalmScript snapshots the script and queues a persistent session locally. `execution serve` warms the VM with compiler-derived pre-session history, keeps one shared armed feed cache for the active paper sessions, and updates the strategy only when a new execution candle closes. Sessions remain in explicit `arming_history` and `arming_live` states until the required feed inventory is ready. If an exchange temporarily returns no fresh bar for the current live append window, the daemon keeps the last closed candle armed and resumes on the next closed candle instead of failing the session.
+When you submit a paper session, PalmScript snapshots the script and queues a persistent session locally. `execution serve` warms the VM with compiler-derived pre-session history, keeps one shared armed feed cache for the active paper sessions, and updates the strategy only when a new execution candle closes. Sessions remain in explicit `arming_history` and `arming_live` states until the required feed inventory is ready. If an exchange temporarily returns no fresh bar for the current live append window, the daemon keeps the last closed candle armed and resumes on the next closed candle instead of failing the session. Perp sessions also stay in `arming_live` and retry when mark-price candles have not caught up to the execution window yet.
 
 The shared quote layer currently provides, per execution alias:
 

web/docs/docs/tooling/cli.fr.md

@@ -162,7 +162,7 @@ The v1 execution layer is intentionally conservative:
 - one persistent local ledger per paper session
 - the same strategy semantics, portfolio caps, cooldowns, and max-bars exits as backtest mode
 
-When you submit a paper session, PalmScript snapshots the script and queues a persistent session locally. `execution serve` warms the VM with compiler-derived pre-session history, keeps one shared armed feed cache for the active paper sessions, and updates the strategy only when a new execution candle closes. Sessions remain in explicit `arming_history` and `arming_live` states until the required feed inventory is ready. If an exchange temporarily returns no fresh bar for the current live append window, the daemon keeps the last closed candle armed and resumes on the next closed candle instead of failing the session.
+When you submit a paper session, PalmScript snapshots the script and queues a persistent session locally. `execution serve` warms the VM with compiler-derived pre-session history, keeps one shared armed feed cache for the active paper sessions, and updates the strategy only when a new execution candle closes. Sessions remain in explicit `arming_history` and `arming_live` states until the required feed inventory is ready. If an exchange temporarily returns no fresh bar for the current live append window, the daemon keeps the last closed candle armed and resumes on the next closed candle instead of failing the session. Perp sessions also stay in `arming_live` and retry when mark-price candles have not caught up to the execution window yet.
 
 The shared quote layer currently provides, per execution alias:
 

web/docs/docs/tooling/cli.ja.md

@@ -162,7 +162,7 @@ The v1 execution layer is intentionally conservative:
 - one persistent local ledger per paper session
 - the same strategy semantics, portfolio caps, cooldowns, and max-bars exits as backtest mode
 
-When you submit a paper session, PalmScript snapshots the script and queues a persistent session locally. `execution serve` warms the VM with compiler-derived pre-session history, keeps one shared armed feed cache for the active paper sessions, and updates the strategy only when a new execution candle closes. Sessions remain in explicit `arming_history` and `arming_live` states until the required feed inventory is ready. If an exchange temporarily returns no fresh bar for the current live append window, the daemon keeps the last closed candle armed and resumes on the next closed candle instead of failing the session.
+When you submit a paper session, PalmScript snapshots the script and queues a persistent session locally. `execution serve` warms the VM with compiler-derived pre-session history, keeps one shared armed feed cache for the active paper sessions, and updates the strategy only when a new execution candle closes. Sessions remain in explicit `arming_history` and `arming_live` states until the required feed inventory is ready. If an exchange temporarily returns no fresh bar for the current live append window, the daemon keeps the last closed candle armed and resumes on the next closed candle instead of failing the session. Perp sessions also stay in `arming_live` and retry when mark-price candles have not caught up to the execution window yet.
 
 The shared quote layer currently provides, per execution alias:
 

web/docs/docs/tooling/cli.md

@@ -156,7 +156,7 @@ The v1 execution layer is intentionally conservative:
 - one persistent local ledger per paper session
 - the same strategy semantics, portfolio caps, cooldowns, and max-bars exits as backtest mode
 
-When you submit a paper session, PalmScript snapshots the script and queues a persistent session locally. `execution serve` warms the VM with compiler-derived pre-session history, keeps one shared armed feed cache for the active paper sessions, and updates the strategy only when a new execution candle closes. Sessions remain in explicit `arming_history` and `arming_live` states until the required feed inventory is ready. If an exchange temporarily returns no fresh bar for the current live append window, the daemon keeps the last closed candle armed and resumes on the next closed candle instead of failing the session.
+When you submit a paper session, PalmScript snapshots the script and queues a persistent session locally. `execution serve` warms the VM with compiler-derived pre-session history, keeps one shared armed feed cache for the active paper sessions, and updates the strategy only when a new execution candle closes. Sessions remain in explicit `arming_history` and `arming_live` states until the required feed inventory is ready. If an exchange temporarily returns no fresh bar for the current live append window, the daemon keeps the last closed candle armed and resumes on the next closed candle instead of failing the session. Perp sessions also stay in `arming_live` and retry when mark-price candles have not caught up to the execution window yet.
 
 The shared quote layer currently provides, per execution alias:
 

web/docs/docs/tooling/cli.pt-BR.md

@@ -162,7 +162,7 @@ The v1 execution layer is intentionally conservative:
 - one persistent local ledger per paper session
 - the same strategy semantics, portfolio caps, cooldowns, and max-bars exits as backtest mode
 
-When you submit a paper session, PalmScript snapshots the script and queues a persistent session locally. `execution serve` warms the VM with compiler-derived pre-session history, keeps one shared armed feed cache for the active paper sessions, and updates the strategy only when a new execution candle closes. Sessions remain in explicit `arming_history` and `arming_live` states until the required feed inventory is ready. If an exchange temporarily returns no fresh bar for the current live append window, the daemon keeps the last closed candle armed and resumes on the next closed candle instead of failing the session.
+When you submit a paper session, PalmScript snapshots the script and queues a persistent session locally. `execution serve` warms the VM with compiler-derived pre-session history, keeps one shared armed feed cache for the active paper sessions, and updates the strategy only when a new execution candle closes. Sessions remain in explicit `arming_history` and `arming_live` states until the required feed inventory is ready. If an exchange temporarily returns no fresh bar for the current live append window, the daemon keeps the last closed candle armed and resumes on the next closed candle instead of failing the session. Perp sessions also stay in `arming_live` and retry when mark-price candles have not caught up to the execution window yet.
 
 The shared quote layer currently provides, per execution alias: