Module position_events 

Position event ingress (JFLOW-C).

Receives live position snapshots from the execution side (Ruby / fks), defines the wire shape, validates inputs, and computes a guidance hint (hold / reduce / exit) the producer can act on. The receiving HTTP handler lives in janus-api; persistence and brain-pipeline-driven guidance refinement are follow-ups.

Structs

Guidance

Advisory guidance returned alongside the receive acknowledgement.

GuidanceThresholds

Threshold ratios used by compute_guidance. Decoupled from OptimizedParams so callers can supply optimizer-derived values when available and fall back to conservative defaults otherwise.

PositionClose

A terminal event: the producer closed a position. Carries the realized outcome so Janus can record what actually happened against the guidance it advised while the position was open. Sent to POST /api/v1/positions/close.

PositionEvent

A snapshot of an open position pushed by the execution side.

PositionOutcome

A closed-trade record joining a PositionClose with the guidance history accumulated in PositionState while the position was open.

PositionState

Rolling per-position state, accumulated across the repeated snapshots a producer pushes for the same position_id. Lets guidance depend on a position’s history (peak profit, prior advice) rather than scoring each snapshot in isolation.

PositionTracker

Stateful refinement layer on top of compute_guidance.

TrailingConfig

Tunables for the stateful guidance layer in PositionTracker.

Enums

GuidanceAction

Guidance action returned to the execution side for an open position.

OutcomeResult

Coarse win/loss classification of a closed trade.

Constants

FEAR_ELEVATED_LEVEL

Fear level (inclusive) at or above which guidance escalates: banks open profit (Reduce) or tightens the stop on a losing position.

FEAR_EXIT_LEVEL

Fear level (inclusive) at or above which guidance exits outright, regardless of P&L — the amygdala equivalent of a crisis regime.

Functions

base_asset

Extract the base asset from a position symbol — "BTC-USD" → "BTC", "ETH/USDT" → "ETH", "BTC" → "BTC". Used to look up per-asset OptimizedParams from a ParamManager.

compute_guidance

Compute advisory guidance for an open position.