Insight Lifecycle

AQE tracks insights through a state machine that includes:

• New
• Executed
• Filled
• Closed
• Cancelled
• Rejected

Typical paths look like:

• New -> Executed -> Filled -> Closed
• New -> Rejected
• Executed -> Cancelled
• Filled -> Closed

Expiry, pipe failures, broker rejections, and trade updates all feed into those transitions.

Amend an Unfilled Entry

An Executed insight has been submitted, but its entry order may still be waiting for a fill. While it remains unfilled, a pipe or other runtime path with &mut Insight can amend the entry price:

Method	Changes	Applicable pending order
insight.update_limit(ctx, price)	The entry limit price	Limit or StopLimit
insight.update_stop_limit(ctx, price)	The entry stop trigger	Stop or StopLimit

For a StopLimit entry, these are separate price components. update_stop_limit does not change the protective stop loss; use update_stop_loss for that. Likewise, update_limit does not change take profit.

InsightPipeResult::from_mutation(insight.update_limit(ctx, 101.0), self.name())

This is a return expression inside an InsightPipe::run method targeting InsightState::Executed. Replace update_limit with update_stop_limit when amending the entry trigger. Use from_mutation so the pipe waits for the broker command instead of treating a queued amendment as completed.

Before submission, either method sets the corresponding price on a New insight locally. For a submitted entry, the price must be finite and positive, the order type must match, the broker order ID must be known, and the broker must advertise AmendLimitPrice or AmendStopPrice respectively. The new price is recorded after the amendment is acknowledged. Once an entry has filled, even partially, or become inactive, the method leaves the entry price unchanged and records a state-history message. A broker that does not support entry amendments returns an error for an active pending order.

See Brokers and Datafeeds for the corresponding broker adapter operation.

Time-To-Live Fields

AQE supports two important lifecycle controls:

• period_unfilled applies while the insight is still New or Executed. Expired insights are rejected or cancellation is requested, depending on state.
• period_till_tp applies once the insight is Filled. Expiry can trigger a close request.

Those checks are enforced by the runtime, not by the UI.

State History

Every significant change can be recorded into state_history, including:

• state transitions
• submission
• broker acceptance
• fills
• partial closes
• cancellation requests
• rejections
• expiry handling

That history is what makes the shared inspector in AQS and Backtest Results useful for review.

Adding A Custom History Message

Use state_log(...) when you want to attach a review note to an insight without changing its lifecycle state. The strategy hook receives insights by shared reference, so add these messages from a pipe or another runtime path that has &mut Insight.

use aq_engine::core::insight::{types::InsightState, Insight};
use aq_engine::core::pipeline::{InsightPipe, InsightPipeBuilder, InsightPipeResult};
use aq_engine::core::strategy::StrategyContext;

pub struct ReviewNotePipe;

impl InsightPipe for ReviewNotePipe {
    fn version(&self) -> &str {
        "1.0"
    }

    fn run(&mut self, _ctx: &mut dyn StrategyContext, insight: &mut Insight) -> InsightPipeResult {
        insight.state_log(Some("Risk check passed".to_string()));

        InsightPipeResult::new(
            true,
            true,
            Some("Review note added to insight history".to_string()),
            self.name().to_string(),
        )
    }
}

Register the pipe on the state where you want the note to be added:

ctx.add_pipe(
    InsightPipeBuilder::new(Box::new(ReviewNotePipe))
        .target_state(InsightState::Filled)
        .build(),
);

state_log(...) keeps the current state, updates updated_at, and appends the supplied message to state_history. If you pass None, AQE records "State log entry".

Persistence

Insight snapshots include execution fields such as filled_price, close_price, broker_realized_pnl, commission, and swap. Live runs sync those snapshots to AQS Cloud, and backtests persist them to the local result database.