Crate of_signals

Expand description

§of_signals

of_signals contains strategy modules that transform analytics snapshots into stable directional state. It is intentionally separated from ingestion/runtime plumbing so strategy logic remains easy to test and evolve.

§Core API

§New In 0.3.0

0.3.0 adds runtime-level replay parity coverage that verifies persisted streams replay into matching signal state. The SignalModule trait and built-in signal constructors remain unchanged.

§New In 0.2.0

Relative to the 0.1.x line, of_signals now includes a broader built-in catalog:

The original trait contract stayed stable, so downstream custom modules do not need a migration.

§Public API Inventory

Public types:

Public constructors:

SignalModule trait methods:

on_analytics(&AnalyticsSnapshot)
snapshot() -> SignalSnapshot
quality_gate(DataQualityFlags) -> SignalGateDecision

Signal output uses of_core::SignalSnapshot and states such as LongBias, ShortBias, Neutral, and Blocked.

§SignalModule Contract

SignalModule is the extension point for strategy logic.

on_analytics(&AnalyticsSnapshot) consumes the latest analytics state and updates internal signal state.
snapshot() returns the last computed SignalSnapshot.
quality_gate(DataQualityFlags) tells the runtime whether the signal should be blocked under the current feed-quality conditions.

Recommended implementation rules:

keep updates deterministic so replay and live runs match
include human-readable reason text in the snapshot when practical
use confidence consistently so downstream hosts can compare modules
block aggressively on stale, gap, or degraded feed conditions when a strategy should not trade through uncertainty

§Constructor Parameter Reference

DeltaMomentumSignal::new takes an absolute delta threshold.
VolumeImbalanceSignal::new takes an absolute session buy_volume - sell_volume threshold.
CumulativeDeltaSignal::new takes an absolute cumulative_delta threshold.
AbsorptionSignal::new takes:
- threshold: directional pressure required before checking for absorption
- price_band: max distance from POC/value location used by the heuristic
ExhaustionSignal::new takes an absolute delta threshold for stalled reversal detection.
SweepDetectionSignal::new takes:
- threshold: directional delta threshold
- breakout_ticks: minimum break outside value area
CompositeSignal::new takes owned child modules and aggregates their votes.

§Delta Momentum Strategy

DeltaMomentumSignal is a reference implementation that:

emits LongBias when delta >= threshold
emits ShortBias when delta <= -threshold
emits Neutral otherwise
emits Blocked in runtime when quality gate fails

§Volume Imbalance Strategy

VolumeImbalanceSignal is a reference implementation that:

compares session buy_volume - sell_volume against an absolute threshold
emits LongBias when buy pressure dominates
emits ShortBias when sell pressure dominates
remains Neutral while the session imbalance stays inside the configured band

§Cumulative Delta Strategy

CumulativeDeltaSignal is a session-bias module that:

compares cumulative_delta against an absolute threshold
emits LongBias when session delta remains strongly positive
emits ShortBias when session delta remains strongly negative
remains Neutral while cumulative delta stays inside the configured band

§Absorption Strategy

AbsorptionSignal is a heuristic module that:

looks for strong directional delta that fails to move price away from POC
emits LongBias on sell absorption near POC
emits ShortBias on buy absorption near POC

§Exhaustion Strategy

ExhaustionSignal is a heuristic reversal module that:

looks for strong directional delta that stalls back near POC
emits ShortBias when buying appears exhausted
emits LongBias when selling appears exhausted

§Sweep Detection Strategy

SweepDetectionSignal is a breakout module that:

looks for strong delta alongside a break outside value area
emits LongBias on upside sweeps
emits ShortBias on downside sweeps

§Composite Strategy

CompositeSignal combines multiple child modules and:

updates each child on the same analytics snapshot
emits the majority directional view when one side has more votes
remains Neutral when there is no directional majority

§Output Interpretation

All built-in modules return SignalSnapshot, which downstream runtimes and bindings expose unchanged.

state is the durable directional state
confidence is a normalized score chosen by the module
reason is short human-readable rationale
quality_flags echoes the quality context that contributed to blocking or caution

Built-in modules are intentionally heuristic rather than venue-specific alpha models. They are meant as production-ready references and defaults, not as the only strategy approach.

§Quick Example

use of_core::{AnalyticsSnapshot, SignalState};
use of_signals::{DeltaMomentumSignal, SignalModule};

let mut signal = DeltaMomentumSignal::new(100);
signal.on_analytics(&AnalyticsSnapshot {
    delta: 150,
    ..Default::default()
});

let snapshot = signal.snapshot();
assert!(matches!(snapshot.state, SignalState::LongBias));

§Alternative Module Example

use of_core::{AnalyticsSnapshot, SignalState};
use of_signals::{SignalModule, VolumeImbalanceSignal};

let mut signal = VolumeImbalanceSignal::new(100);
signal.on_analytics(&AnalyticsSnapshot {
    buy_volume: 350,
    sell_volume: 200,
    ..Default::default()
});

let snapshot = signal.snapshot();
assert!(matches!(snapshot.state, SignalState::LongBias));

§Composite Example

use of_core::{AnalyticsSnapshot, SignalState};
use of_signals::{
    CompositeSignal, CumulativeDeltaSignal, DeltaMomentumSignal, SignalModule,
    VolumeImbalanceSignal,
};

let mut signal = CompositeSignal::new(vec![
    Box::new(DeltaMomentumSignal::new(100)),
    Box::new(VolumeImbalanceSignal::new(100)),
    Box::new(CumulativeDeltaSignal::new(150)),
]);
signal.on_analytics(&AnalyticsSnapshot {
    delta: 200,
    cumulative_delta: 250,
    buy_volume: 400,
    sell_volume: 100,
    ..Default::default()
});

let snapshot = signal.snapshot();
assert!(matches!(snapshot.state, SignalState::LongBias));

§Quality Gate Example

use of_core::DataQualityFlags;
use of_signals::{DeltaMomentumSignal, SignalGateDecision, SignalModule};

let signal = DeltaMomentumSignal::default();
let gate = signal.quality_gate(DataQualityFlags::SEQUENCE_GAP);
assert_eq!(gate, SignalGateDecision::Block);

§Implementing Your Own Signal Module

Implement SignalModule and keep it:

deterministic (important for replay parity)
explicit about confidence and reason fields
strict about quality gating for unsafe feed states
compatible with the stable SignalSnapshot contract so bindings and FFI callers keep working

§Real-World Use Cases

§1. Gate entries on feed quality

Even a simple threshold signal becomes materially safer when quality_gate(...) blocks action during stale, gap, or degraded feed states.

§2. Build multi-factor orderflow strategies

Use several modules together to express:

context: CumulativeDeltaSignal
trigger: SweepDetectionSignal
reversal filter: AbsorptionSignal or ExhaustionSignal

§3. Keep strategy logic deterministic in replay

Because modules consume normalized analytics instead of live provider payloads, the same module can be replayed over historical sessions and compared to live behavior with much less drift.

§Strategy Pattern: Composite Confirmation

A practical strategy stack often looks like:

CumulativeDeltaSignal for directional regime bias
VolumeImbalanceSignal for immediate orderflow pressure
SweepDetectionSignal for breakout confirmation
CompositeSignal to require majority confirmation

§Detailed Example: Build A Composite Intraday Bias Module

use of_core::{AnalyticsSnapshot, DataQualityFlags, SignalState};
use of_signals::{
    CompositeSignal, CumulativeDeltaSignal, SweepDetectionSignal, SignalGateDecision,
    SignalModule, VolumeImbalanceSignal,
};

fn main() {
    let mut signal = CompositeSignal::new(vec![
        Box::new(CumulativeDeltaSignal::new(400)),
        Box::new(VolumeImbalanceSignal::new(150)),
        Box::new(SweepDetectionSignal::new(200, 4)),
    ]);

    let analytics = AnalyticsSnapshot {
        buy_volume: 900,
        sell_volume: 500,
        delta: 400,
        cumulative_delta: 650,
        last_price: 505_075,
        point_of_control: 505_000,
        value_area_low: 504_750,
        value_area_high: 505_050,
        ..Default::default()
    };

    if signal.quality_gate(DataQualityFlags::NONE) == SignalGateDecision::Pass {
        signal.on_analytics(&analytics);
        let snapshot = signal.snapshot();
        if matches!(snapshot.state, SignalState::LongBias) {
            println!("long bias: {}", snapshot.reason);
        }
    }
}

§Detailed Example: Write Your Own Signal Module

use of_core::{AnalyticsSnapshot, DataQualityFlags, SignalSnapshot, SignalState};
use of_signals::{SignalGateDecision, SignalModule};

struct POCReclaimSignal {
    last: SignalSnapshot,
}

impl Default for POCReclaimSignal {
    fn default() -> Self {
        Self {
            last: SignalSnapshot {
                module_id: "poc_reclaim_v1",
                state: SignalState::Neutral,
                confidence_bps: 0,
                quality_flags: 0,
                reason: "init".to_string(),
            },
        }
    }
}

impl SignalModule for POCReclaimSignal {
    fn on_analytics(&mut self, analytics: &AnalyticsSnapshot) {
        let state = if analytics.delta > 200 && analytics.point_of_control >= analytics.value_area_low {
            SignalState::LongBias
        } else if analytics.delta < -200 && analytics.point_of_control <= analytics.value_area_high {
            SignalState::ShortBias
        } else {
            SignalState::Neutral
        };

        self.last = SignalSnapshot {
            module_id: "poc_reclaim_v1",
            state,
            confidence_bps: 7000,
            reason: "POC reclaim heuristic".to_string(),
            quality_flags: 0,
        };
    }

    fn snapshot(&self) -> SignalSnapshot {
        self.last.clone()
    }

    fn quality_gate(&self, flags: DataQualityFlags) -> SignalGateDecision {
        if flags.intersects(
            DataQualityFlags::STALE_FEED
                | DataQualityFlags::SEQUENCE_GAP
                | DataQualityFlags::ADAPTER_DEGRADED,
        ) {
            SignalGateDecision::Block
        } else {
            SignalGateDecision::Pass
        }
    }
}

Structs§

AbsorptionSignal: Absorption signal that looks for strong directional flow failing to dislodge price from POC.
CompositeSignal: Composite signal that aggregates child modules into one stable directional output.
CumulativeDeltaSignal: Cumulative delta signal tuned for session-scale directional bias.
DeltaMomentumSignal: Reference implementation: simple delta momentum threshold signal.
ExhaustionSignal: Exhaustion signal that looks for strong directional flow stalling back near POC.
SweepDetectionSignal: Sweep detection signal that looks for value-area breaks accompanied by directional flow.
VolumeImbalanceSignal: Volume imbalance signal based on buy/sell session totals.

Enums§

SignalGateDecision: Result of running quality-gate checks.

Traits§

SignalModule: Trait implemented by signal modules consumed by the runtime.

Crate of_signals

Crate of_signals Copy item path

§of_signals

§Core API

§New In 0.3.0

§New In 0.2.0

§Public API Inventory

§SignalModule Contract

§Constructor Parameter Reference

§Delta Momentum Strategy

§Volume Imbalance Strategy

§Cumulative Delta Strategy

§Absorption Strategy

§Exhaustion Strategy

§Sweep Detection Strategy

§Composite Strategy

§Output Interpretation

§Quick Example

§Alternative Module Example

§Composite Example

§Quality Gate Example

§Implementing Your Own Signal Module

§Real-World Use Cases

§1. Gate entries on feed quality

§2. Build multi-factor orderflow strategies

§3. Keep strategy logic deterministic in replay

§Strategy Pattern: Composite Confirmation

§Detailed Example: Build A Composite Intraday Bias Module

§Detailed Example: Write Your Own Signal Module

Structs§

Enums§

Traits§

Crate of_signals