Interface for state instance implementations. Defines the contract for local, persist, and dummy backends.
Intended use: per-signal mutable state for LLM-driven strategies that track trade confirmation metrics across the position lifetime — e.g. peak unrealised PnL, minutes since entry, and capitulation thresholds.
Example shape:
{ peakPercent: number; minutesOpen: number }
Profitable trades endure -0.5–2.5% drawdown yet still reach peak 2–3%+. SL trades either never go positive (Feb25) or show peak < 0.15% (Feb08, Feb13). Capitulation rule: if position open N minutes and peak < threshold (e.g. 0.3%) — LLM thesis was not confirmed by market, exit immediately.
waitForInit: (initial: boolean) => Promise<void>
Initialize the state instance.
getState: <Value extends object = object>(when: Date) => Promise<Value>
Read the current state value.
Returns initialValue when the stored when is greater than the requested when
(look-ahead bias protection).
setState: <Value extends object = object>(dispatch: Value | Dispatch<Value>, when: Date) => Promise<Value>
Update the state value.
A write with a smaller when overwrites an existing record —
that lets a restarted backtest reset live-written state without breaking live.
The dispatch updater receives the look-ahead-guarded current value
(or initialValue when the stored when is in the future).
dispose: () => Promise<void>
Releases any resources held by this instance.