AvwapLib

Library "AvwapLib"
Shared functions: AVWAP, stage classification, position sizing,
swing detection, and risk helpers. Used by all strategy() scripts.
NOTE: rs_vs_spy() cannot live here (request.security() banned in
library exports) — each strategy implements it inline.

avwap(src, anchor_bar, max_lookback)
  Anchored VWAP from a specific bar to current bar.
Uses loop approach with bounded max_lookback for robustness.
  Parameters:
    src (float): Source price (typically hlc3)
    anchor_bar (int): Bar index of anchor point (from find_swing_high/low)
    max_lookback (simple int): Maximum bars to look back (cap for performance, default 500 ~2yr daily)
  Returns: AVWAP value, or na if anchor invalid or out of range

avwap_slope(avwap_val, lookback)
  AVWAP slope — rate of change over lookback period.
  Parameters:
    avwap_val (float): AVWAP series
    lookback (simple int): Number of bars for slope calculation
  Returns: Slope (positive = rising, negative = falling), or na

dcr()
  Daily Closing Range — where price closed within the bar's range.
  Returns: DCR as percentage (0 = closed at low, 100 = closed at high)

rvol(period)
  Relative Volume — current bar volume vs historical average.
Uses volume[1] offset to avoid including current bar in average.
  Parameters:
    period (simple int): Lookback period for average calculation
  Returns: RVOL ratio (>1 = above average)

is_stage2()
  Stage 2 check (simplified Weinstein model).
Conditions: price > SMA50, SMA50 rising (vs 10 bars ago), price > SMA200.
  Returns: true if all Stage 2 conditions met

calc_shares(entry, stop, risk_pct, equity)
  Position size: shares = floor(equity * risk% / risk_per_share).
  Parameters:
    entry (float): Entry price
    stop (float): Stop-loss price
    risk_pct (float): Risk as decimal (0.01 = 1%)
    equity (float): Account equity
  Returns: Number of shares (integer), 0 if invalid

rr_valid(entry, stop, target, min_rr)
  Validate risk/reward ratio meets minimum threshold.
  Parameters:
    entry (float): Entry price
    stop (float): Stop-loss price
    target (float): Target price
    min_rr (float): Minimum required R:R (e.g., 2.0 for 1:2)
  Returns: true if R:R >= min_rr

confirmed()
  Returns true only on confirmed (closed) bars.
MUST gate every entry/exit signal to prevent repainting.
  Returns: true if bar is confirmed

find_swing_high(strength)
  Bar index of the most recent confirmed swing high.
Uses ta.pivothigh — confirmed 'strength' bars after the actual high.
Result persists (via var) until a new swing high is detected.
  Parameters:
    strength (simple int): Number of bars required on each side to confirm pivot
  Returns: Bar index of last swing high, or na if none found yet

find_swing_low(strength)
  Bar index of the most recent confirmed swing low.
Uses ta.pivotlow — confirmed 'strength' bars after the actual low.
Result persists (via var) until a new swing low is detected.
  Parameters:
    strength (simple int): Number of bars required on each side to confirm pivot
  Returns: Bar index of last swing low, or na if none found yet