@hoox-sh/pynets 0.2.0 → 0.4.0

package/src/runtime/ta.ts

@@ -55,6 +55,12 @@ interface HighestLowestState {
   window: Cell[];
 }
 
+interface AroonState {
+  length: number;
+  highs: Cell[];
+  lows: Cell[];
+}
+
 interface StdevState {
   period: number;
   window: Cell[];
@@ -249,7 +255,80 @@ interface VolIndexState {
 }
 
 interface WvadState {
-  value: number;
+  period: number;
+  vols: number[];
+  volSum: number;
+}
+
+interface CmfState {
+  period: number;
+  mf: number[];
+  vol: number[];
+  mfSum: number;
+  volSum: number;
+}
+
+interface KlingerState {
+  prev: Cell;
+  cum: number;
+  started: boolean;
+}
+
+interface UoState {
+  n1: number;
+  n2: number;
+  n3: number;
+  prev: Cell;
+  window: Array<[Cell, Cell]>;
+}
+
+interface RciState {
+  length: number;
+  window: Cell[];
+}
+
+interface DpoState {
+  length: number;
+  window: Cell[];
+}
+
+interface KstState {
+  key: string;
+  window: Cell[];
+}
+
+interface StochRsiState {
+  rsiLen: number;
+  stochLen: number;
+  prices: number[];
+  rsiRing: number[];
+  bars: number;
+  validRsi: number;
+  signal: number | null;
+}
+
+interface BbPctState {
+  length: number;
+  window: Cell[];
+}
+
+interface EmvState {
+  length: number;
+  prevH: Cell;
+  prevL: Cell;
+  started: boolean;
+  valid: number[];
+}
+
+interface FractalState {
+  period: number;
+  highs: Cell[];
+  lows: Cell[];
+  bars: number;
+}
+
+interface ZigzagState {
+  samples: Cell[];
 }
 
 export type PivotPoints = {
@@ -264,6 +343,25 @@ function finiteCell(value: Cell): Cell {
   return value !== null && Number.isFinite(value) ? value : null;
 }
 
+/** Plain dict returned by `ta.*` handlers. Attribute reads are brand-gated. */
+export interface TaRecord {
+  readonly __taRecord: true;
+  [key: string]: number | null | boolean | string;
+}
+
+function taRec(fields: Record<string, number | null | boolean | string>): TaRecord {
+  return { __taRecord: true, ...fields };
+}
+
+function pushCap<T>(window: T[], value: T, cap: number): void {
+  if (window.length === cap) window.shift();
+  window.push(value);
+}
+
+function finiteOut(value: number): Cell {
+  return Number.isFinite(value) ? value : null;
+}
+
 /** Near-integer floats round (14.0000000001 → 14); else floor. Python `_float_to_period_int`. */
 const PERIOD_INT_EPS = 1e-9;
 
@@ -349,6 +447,18 @@ export class TaEngine {
   private readonly nviSites = new Map<string, VolIndexState>();
   private readonly pviSites = new Map<string, VolIndexState>();
   private readonly wvadSites = new Map<string, WvadState>();
+  private readonly cmfSites = new Map<string, CmfState>();
+  private readonly klingerSites = new Map<string, KlingerState>();
+  private readonly aroonSites = new Map<string, AroonState>();
+  private readonly uoSites = new Map<string, UoState>();
+  private readonly rciSites = new Map<string, RciState>();
+  private readonly dpoSites = new Map<string, DpoState>();
+  private readonly kstSites = new Map<string, KstState>();
+  private readonly stochRsiSites = new Map<string, StochRsiState>();
+  private readonly bbPctSites = new Map<string, BbPctState>();
+  private readonly emvSites = new Map<string, EmvState>();
+  private readonly fractalSites = new Map<string, FractalState>();
+  private readonly zigzagSites = new Map<string, ZigzagState>();
 
   sma(site: string, source: Cell, period: number): Cell {
     const n = pinePeriod(period);
@@ -1597,10 +1707,11 @@ export class TaEngine {
   }
 
   /**
-   * Williams AD. First bar 0; close>prev → +(close-low); close<prev →
-   * -(high-close). H/L/C na keeps previous (`_wad`).
+   * Williams AD (`_wad_inc_update`). First bar 0. Later: up adds
+   * vol*(close-low); down subtracts vol*(high-close). Missing H/L
+   * fallback to close; vol na → 0.
    */
-  wad(site: string, high: Cell, low: Cell, close: Cell): Cell {
+  wad(site: string, high: Cell, low: Cell, close: Cell, volume: Cell): Cell {
     let st = this.wadSites.get(site);
     if (st === undefined) {
       st = { wad: 0, prev: null, started: false };
@@ -1609,18 +1720,21 @@ export class TaEngine {
     const h = finiteCell(high);
     const l = finiteCell(low);
     const c = finiteCell(close);
-    if (h === null || l === null || c === null) return st.wad;
+    const vv = finiteCell(volume) ?? 0;
     if (!st.started) {
       st.started = true;
       st.prev = c;
-      return st.wad;
+      st.wad = 0;
+      return 0;
     }
     const prev = st.prev;
-    if (prev !== null) {
-      if (c > prev) st.wad += c - l;
-      else if (c < prev) st.wad -= h - c;
+    if (c !== null && prev !== null) {
+      const hi = h ?? c;
+      const lo = l ?? c;
+      if (c > prev) st.wad += vv * (c - lo);
+      else if (c < prev) st.wad -= vv * (hi - c);
     }
-    st.prev = c;
+    if (c !== null) st.prev = c;
     return st.wad;
   }
 
@@ -1684,24 +1798,90 @@ export class TaEngine {
   }
 
   /**
-   * Williams Variable AD: cumulative ((c-o)/(h-l))*volume. O/H/L/C na keeps
-   * previous; vol na → 0; zero range adds 0.
+   * Williams Volume AD (`_wvad_inc_update`): last WAD / rolling volume sum.
+   * period<=0 or zero vol sum → 0. Nested WAD uses `${site}:wad`.
    */
-  wvad(site: string, open: Cell, high: Cell, low: Cell, close: Cell, volume: Cell): Cell {
+  wvad(site: string, high: Cell, low: Cell, close: Cell, volume: Cell, period: number): Cell {
+    const wad = this.wad(`${site}:wad`, high, low, close, volume);
+    const n = Number.isFinite(period) ? Math.trunc(period) : 0;
+    if (n <= 0) return 0;
     let st = this.wvadSites.get(site);
-    if (st === undefined) {
-      st = { value: 0 };
+    if (st === undefined || st.period !== n) {
+      st = { period: n, vols: [], volSum: 0 };
       this.wvadSites.set(site, st);
     }
-    const o = finiteCell(open);
+    const vv = finiteCell(volume) ?? 0;
+    if (st.vols.length === n) st.volSum -= st.vols.shift()!;
+    st.vols.push(vv);
+    st.volSum += vv;
+    if (st.volSum > 0 && wad !== null) return wad / st.volSum;
+    return 0;
+  }
+
+  /**
+   * Chaikin Money Flow (`_cmf_inc_update`). CLV*vol rolling window.
+   * period<=0 → na; zero vol sum → 0; missing H/L/C → clv 0.
+   */
+  cmf(site: string, high: Cell, low: Cell, close: Cell, volume: Cell, period: number): Cell {
+    const n = Number.isFinite(period) ? Math.trunc(period) : 0;
+    if (n <= 0) return null;
+    let st = this.cmfSites.get(site);
+    if (st === undefined || st.period !== n) {
+      st = { period: n, mf: [], vol: [], mfSum: 0, volSum: 0 };
+      this.cmfSites.set(site, st);
+    }
     const h = finiteCell(high);
     const l = finiteCell(low);
     const c = finiteCell(close);
-    if (o === null || h === null || l === null || c === null) return st.value;
-    const rng = h - l;
     const vv = finiteCell(volume) ?? 0;
-    if (rng !== 0) st.value += ((c - o) / rng) * vv;
-    return st.value;
+    let clv = 0;
+    if (h !== null && l !== null && c !== null) {
+      const rng = h - l;
+      clv = rng === 0 ? 0 : ((c - l) - (h - c)) / rng;
+    }
+    const mf = clv * vv;
+    if (st.mf.length === n) {
+      st.mfSum -= st.mf.shift()!;
+      st.volSum -= st.vol.shift()!;
+    }
+    st.mf.push(mf);
+    st.vol.push(vv);
+    st.mfSum += mf;
+    st.volSum += vv;
+    return st.volSum > 0 ? st.mfSum / st.volSum : 0;
+  }
+
+  /**
+   * Klinger oscillator (`_klinger_inc_update`): signed-volume cumulant,
+   * then EMA(fast)−EMA(slow) via `${site}:fast` / `${site}:slow`.
+   */
+  klinger(site: string, close: Cell, volume: Cell, fast: number, slow: number): Cell {
+    let st = this.klingerSites.get(site);
+    if (st === undefined) {
+      st = { prev: null, cum: 0, started: false };
+      this.klingerSites.set(site, st);
+    }
+    const c = finiteCell(close);
+    const vv = finiteCell(volume) ?? 0;
+    if (!st.started) {
+      st.started = true;
+      st.prev = c;
+      st.cum = 0;
+    } else {
+      const prev = st.prev;
+      let trv = 0;
+      if (c !== null && prev !== null) {
+        if (c > prev) trv = vv;
+        else if (c < prev) trv = -vv;
+      }
+      st.cum += trv;
+      if (c !== null) st.prev = c;
+    }
+    const fastV = this.ema(`${site}:fast`, st.cum, fast);
+    const slowV = this.ema(`${site}:slow`, st.cum, slow);
+    if (fastV === null || slowV === null) return null;
+    const out = fastV - slowV;
+    return Number.isFinite(out) ? out : null;
   }
 
   /**
@@ -2090,4 +2270,850 @@ export class TaEngine {
   min(site: string, source: Cell, period: number): Cell {
     return this.lowest(site, source, period);
   }
+
+  /**
+   * Awesome Oscillator: SMA(hl2, fast) − SMA(hl2, slow). Default 5 / 34.
+   * Warm-up until the slow window is full (`_builtin_ta_ao`).
+   */
+  ao(site: string, high: Cell, low: Cell, fast = 5, slow = 34): Cell {
+    const f = pinePeriod(fast);
+    const s = pinePeriod(slow);
+    if (f === null || s === null) return null;
+    const h = finiteCell(high);
+    const l = finiteCell(low);
+    const hl2 = h !== null && l !== null ? (h + l) / 2 : null;
+    const fv = this.sma(`${site}:ao:fast:${f}`, hl2, f);
+    const sv = this.sma(`${site}:ao:slow:${s}`, hl2, s);
+    if (fv === null || sv === null) return null;
+    const out = fv - sv;
+    return Number.isFinite(out) ? out : null;
+  }
+
+  /**
+   * Aroon pair `{down, up}`. Window is `length + 1`; ties keep the oldest
+   * extreme (`_builtin_ta_aroon` / `numba_aroon`).
+   */
+  aroon(
+    site: string,
+    high: Cell,
+    low: Cell,
+    length = 14,
+  ): { down: Cell; up: Cell } {
+    const n = pinePeriod(length);
+    const na = { down: null, up: null };
+    if (n === null) return na;
+    const window = n + 1;
+    let st = this.aroonSites.get(site);
+    if (st === undefined || st.length !== n) {
+      st = { length: n, highs: [], lows: [] };
+      this.aroonSites.set(site, st);
+    }
+    if (st.highs.length === window) {
+      st.highs.shift();
+      st.lows.shift();
+    }
+    st.highs.push(finiteCell(high));
+    st.lows.push(finiteCell(low));
+    if (st.highs.length < window) return na;
+    let hh: number | null = null;
+    let ll: number | null = null;
+    let hhK = 0;
+    let llK = 0;
+    for (let k = 0; k < window; k++) {
+      const hv = st.highs[k]!;
+      const lv = st.lows[k]!;
+      if (hv === null || lv === null) return na;
+      if (hh === null || hv > hh) {
+        hh = hv;
+        hhK = k;
+      }
+      if (ll === null || lv < ll) {
+        ll = lv;
+        llK = k;
+      }
+    }
+    const barsSinceHh = window - 1 - hhK;
+    const barsSinceLl = window - 1 - llK;
+    const up = (100 * (n - barsSinceHh)) / n;
+    const down = (100 * (n - barsSinceLl)) / n;
+    return {
+      down: Number.isFinite(down) ? down : null,
+      up: Number.isFinite(up) ? up : null,
+    };
+  }
+
+  /**
+   * Ultimate Oscillator. BP/TR window; first bar has no prev close.
+   * Weights 4, 2, 1. Ready once the longest window is all finite (`_uo_inc_update`).
+   */
+  uo(site: string, high: Cell, low: Cell, close: Cell, n1: number, n2: number, n3: number): Cell {
+    const a = pinePeriod(n1);
+    const b = pinePeriod(n2);
+    const c = pinePeriod(n3);
+    if (a === null || b === null || c === null) return null;
+    const need = Math.max(a, b, c);
+    let st = this.uoSites.get(site);
+    if (st === undefined || st.n1 !== a || st.n2 !== b || st.n3 !== c) {
+      st = { n1: a, n2: b, n3: c, prev: null, window: [] };
+      this.uoSites.set(site, st);
+    }
+    const h = finiteCell(high);
+    const l = finiteCell(low);
+    const cl = finiteCell(close);
+    const prev = st.prev;
+    st.prev = cl;
+    let bp: Cell = null;
+    let tr: Cell = null;
+    if (prev !== null && h !== null && l !== null && cl !== null) {
+      const lowRef = l < prev ? l : prev;
+      const highRef = h > prev ? h : prev;
+      bp = cl - lowRef;
+      tr = highRef - lowRef;
+    }
+    pushCap(st.window, [bp, tr], need);
+    if (st.window.length < need) return null;
+    const avg = (length: number): Cell => {
+      let bpS = 0;
+      let trS = 0;
+      const start = st.window.length - length;
+      for (let i = start; i < st.window.length; i++) {
+        const pair = st.window[i]!;
+        if (pair[0] === null || pair[1] === null) return null;
+        bpS += pair[0];
+        trS += pair[1];
+      }
+      if (trS === 0) return null;
+      return bpS / trS;
+    };
+    const a1 = avg(a);
+    const a2 = avg(b);
+    const a3 = avg(c);
+    if (a1 === null || a2 === null || a3 === null) return null;
+    return finiteOut((100 * (4 * a1 + 2 * a2 + a3)) / 7);
+  }
+
+  /**
+   * Rank Correlation Index: Spearman rho of time vs value (not ×100).
+   * Length < 2 raises, matching `_builtin_ta_rci` (not the kernel's soft na).
+   */
+  rci(site: string, source: Cell, length: number): Cell {
+    const n = pinePeriod(length);
+    if (n === null || n < 2) {
+      throw new Error("ta.rci length must be at least 2");
+    }
+    let st = this.rciSites.get(site);
+    if (st === undefined || st.length !== n) {
+      st = { length: n, window: [] };
+      this.rciSites.set(site, st);
+    }
+    pushCap(st.window, finiteCell(source), n);
+    if (st.window.length < n) return null;
+    const vals: number[] = [];
+    for (const v of st.window) {
+      if (v === null) return null;
+      vals.push(v);
+    }
+    return spearmanRho(vals);
+  }
+
+  /** `close[length//2+1] - sma(close, length)` (`_dpo_inc_update`). Any na in the window → na. */
+  dpo(site: string, close: Cell, length: number): Cell {
+    const n = pinePeriod(length);
+    if (n === null) return null;
+    const disp = Math.floor(n / 2) + 1;
+    const keep = Math.max(n, disp);
+    let st = this.dpoSites.get(site);
+    if (st === undefined || st.length !== n) {
+      st = { length: n, window: [] };
+      this.dpoSites.set(site, st);
+    }
+    const x = finiteCell(close);
+    pushCap(st.window, x, keep);
+    if (st.window.length < n || st.window.length < disp) return null;
+    const smaStart = st.window.length - n;
+    if (x === null) return null;
+    let sum = 0;
+    for (let i = smaStart; i < st.window.length; i++) {
+      const v = st.window[i]!;
+      if (v === null) return null;
+      sum += v;
+    }
+    const displaced = st.window[st.window.length - disp];
+    if (displaced === null || displaced === undefined) return null;
+    return finiteOut(displaced - sum / n);
+  }
+
+  /**
+   * Know Sure Thing. ROC is `(close - close[-length]) / close[-length] * 100`
+   * (lookback `length`, not `length` bars via `src[length]`). Weights 1/2/3/4, /10.
+   */
+  kst(site: string, close: Cell, l1: number, l2: number, l3: number, l4: number): Cell {
+    const lengths = [pinePeriod(l1), pinePeriod(l2), pinePeriod(l3), pinePeriod(l4)];
+    if (lengths.some((v) => v === null)) return null;
+    const ns = lengths as number[];
+    if (Math.min(...ns) < 1) return null;
+    const keep = Math.max(...ns);
+    const key = ns.join(",");
+    let st = this.kstSites.get(site);
+    if (st === undefined || st.key !== key) {
+      st = { key, window: [] };
+      this.kstSites.set(site, st);
+    }
+    const x = finiteCell(close);
+    pushCap(st.window, x, keep);
+    if (st.window.length < keep || x === null) return null;
+    const rocs: number[] = [];
+    for (const length of ns) {
+      const base = st.window[st.window.length - length];
+      if (base === null || base === undefined) return null;
+      if (base === 0) rocs.push(0);
+      else rocs.push(((x - base) / base) * 100);
+    }
+    return finiteOut((rocs[0]! * 1 + rocs[1]! * 2 + rocs[2]! * 3 + rocs[3]! * 4) / 10);
+  }
+
+  /**
+   * StochRSI. Simple (non-Wilder) RSI: sum of gains/losses over `rsiLen` closes
+   * divided by `rsiLen`. First RSI omits the oldest close (`bars > rsiLen`).
+   * Signal is `0.33 * stoch + 0.67 * prev` (`_stochrsi_inc_update`).
+   */
+  stochRsi(site: string, close: Cell, rsiLength: number, stochLength: number): TaRecord {
+    const empty = taRec({ stochrsi: null, signal: null });
+    const rsiLen = pinePeriod(rsiLength);
+    const stochLen = pinePeriod(stochLength);
+    if (rsiLen === null || stochLen === null) return empty;
+    let st = this.stochRsiSites.get(site);
+    if (st === undefined || st.rsiLen !== rsiLen || st.stochLen !== stochLen) {
+      st = {
+        rsiLen,
+        stochLen,
+        prices: [],
+        rsiRing: [],
+        bars: 0,
+        validRsi: 0,
+        signal: null,
+      };
+      this.stochRsiSites.set(site, st);
+    }
+    const x = finiteCell(close);
+    if (x === null) return taRec({ stochrsi: null, signal: st.signal });
+    pushCap(st.prices, x, rsiLen);
+    st.bars += 1;
+    if (st.bars <= rsiLen) return empty;
+    if (st.prices.length < rsiLen) return empty;
+    let gains = 0;
+    let losses = 0;
+    for (let j = 1; j < st.prices.length; j++) {
+      const d = st.prices[j]! - st.prices[j - 1]!;
+      if (d > 0) gains += d;
+      else losses += -d;
+    }
+    const avgGain = gains / rsiLen;
+    const avgLoss = losses / rsiLen;
+    const rs = avgLoss !== 0 ? avgGain / avgLoss : 100;
+    const rsiVal = 100 - 100 / (1 + rs);
+    pushCap(st.rsiRing, rsiVal, stochLen);
+    st.validRsi += 1;
+    if (st.validRsi < stochLen || st.rsiRing.length < stochLen) return empty;
+    let rsiHigh = st.rsiRing[0]!;
+    let rsiLow = rsiHigh;
+    for (const v of st.rsiRing) {
+      if (v > rsiHigh) rsiHigh = v;
+      if (v < rsiLow) rsiLow = v;
+    }
+    const rsiRange = rsiHigh - rsiLow;
+    const stoch = rsiRange === 0 ? 0 : ((rsiVal - rsiLow) / rsiRange) * 100;
+    const prev = st.signal === null ? stoch : st.signal;
+    const signal = stoch * 0.33 + prev * 0.67;
+    st.signal = signal;
+    return taRec({
+      stochrsi: finiteOut(stoch),
+      signal: finiteOut(signal),
+    });
+  }
+
+  /** Donchian channel via nested highest/lowest (`_donchian_inc_update`). */
+  donchian(site: string, high: Cell, low: Cell, length: number): TaRecord {
+    const empty = taRec({ high: null, low: null, mid: null });
+    const hi = this.highest(`${site}:hi`, high, length);
+    const lo = this.lowest(`${site}:lo`, low, length);
+    if (hi === null || lo === null) return empty;
+    return taRec({ high: hi, low: lo, mid: (hi + lo) / 2 });
+  }
+
+  /**
+   * Ichimoku. Tenkan/kijun are high-low midpoints. Senkou B is fixed at 52
+   * (`ICHIMOKU_SENKOU_B_PERIOD`), not `2 * slow`.
+   */
+  ichimoku(site: string, high: Cell, low: Cell, fast: number, slow: number): TaRecord {
+    const mid = (tag: string, period: number): Cell => {
+      const hi = this.highest(`${site}:${tag}:hi`, high, period);
+      const lo = this.lowest(`${site}:${tag}:lo`, low, period);
+      if (hi === null || lo === null) return null;
+      return (hi + lo) / 2;
+    };
+    const tenkan = mid("tenkan", fast);
+    const kijun = mid("kijun", slow);
+    const senkouA = tenkan !== null && kijun !== null ? (tenkan + kijun) / 2 : null;
+    const senkouB = mid("spanb", 52);
+    return taRec({
+      tenkan_sen: tenkan,
+      kijun_sen: kijun,
+      senkou_span_a: senkouA,
+      senkou_span_b: senkouB,
+    });
+  }
+
+  /** Bollinger %B × 100, population variance (`/ length`), clamped to 0..100. */
+  bbPct(site: string, close: Cell, length: number, mult: number): Cell {
+    const n = pinePeriod(length);
+    if (n === null) return null;
+    const m = Number.isFinite(mult) ? mult : 2;
+    let st = this.bbPctSites.get(site);
+    if (st === undefined || st.length !== n) {
+      st = { length: n, window: [] };
+      this.bbPctSites.set(site, st);
+    }
+    pushCap(st.window, finiteCell(close), n);
+    if (st.window.length < n) return null;
+    let sum = 0;
+    for (const v of st.window) {
+      if (v === null) return null;
+      sum += v;
+    }
+    const sma = sum / n;
+    let varSum = 0;
+    for (const v of st.window) {
+      const d = v! - sma;
+      varSum += d * d;
+    }
+    const std = Math.sqrt(varSum / n);
+    const upper = sma + std * m;
+    const lower = sma - std * m;
+    if (upper === lower) return 50;
+    const last = st.window[st.window.length - 1]!;
+    let pct = ((last - lower) / (upper - lower)) * 100;
+    if (pct < 0) pct = 0;
+    if (pct > 100) pct = 100;
+    return finiteOut(pct);
+  }
+
+  /**
+   * Ease of Movement, SMA of the last `length` finite EMV samples
+   * (na bars are skipped, not zeros). Bar 0 is na.
+   */
+  emv(site: string, high: Cell, low: Cell, volume: Cell, length: number): Cell {
+    const n = pinePeriod(length);
+    if (n === null) return null;
+    let st = this.emvSites.get(site);
+    if (st === undefined || st.length !== n) {
+      st = { length: n, prevH: null, prevL: null, started: false, valid: [] };
+      this.emvSites.set(site, st);
+    }
+    const h = finiteCell(high);
+    const l = finiteCell(low);
+    const vol = finiteCell(volume);
+    if (!st.started) {
+      st.started = true;
+      st.prevH = h;
+      st.prevL = l;
+      return null;
+    }
+    let sample: number | null = null;
+    if (h !== null && l !== null && vol !== null && vol !== 0 && st.prevH !== null && st.prevL !== null) {
+      const distance = (h + l) / 2 - (st.prevH + st.prevL) / 2;
+      const box = h - l;
+      if (box !== 0) {
+        const emv = (distance / box) * (h - l) / vol;
+        sample = Number.isFinite(emv) ? emv : null;
+      }
+    }
+    st.prevH = h;
+    st.prevL = l;
+    if (sample !== null) pushCap(st.valid, sample, n);
+    if (st.valid.length < n) return null;
+    let sum = 0;
+    for (const v of st.valid) sum += v;
+    return finiteOut(sum / n);
+  }
+
+  /**
+   * Fractal flags. Python evaluates at the series end, so the forward half of
+   * the centered window is empty: once `bars >= 2*period+1`, current equals
+   * the extreme of the last `period+1` bars (ties count). Warmup is false, not na.
+   */
+  fractal(site: string, high: Cell, low: Cell, period: number): TaRecord {
+    const none = taRec({ is_high_fractal: false, is_low_fractal: false });
+    const n = pinePeriod(period);
+    if (n === null) return none;
+    const win = n + 1;
+    const need = n * 2 + 1;
+    let st = this.fractalSites.get(site);
+    if (st === undefined || st.period !== n) {
+      st = { period: n, highs: [], lows: [], bars: 0 };
+      this.fractalSites.set(site, st);
+    }
+    st.bars += 1;
+    pushCap(st.highs, finiteCell(high), win);
+    pushCap(st.lows, finiteCell(low), win);
+    if (st.bars < need || st.highs.length < win) return none;
+    const ch = st.highs[st.highs.length - 1]!;
+    const cl = st.lows[st.lows.length - 1]!;
+    if (ch === null || cl === null) return none;
+    let maxH = ch;
+    let minL = cl;
+    for (const h of st.highs) {
+      if (h === null) return none;
+      if (h > maxH) maxH = h;
+    }
+    for (const l of st.lows) {
+      if (l === null) return none;
+      if (l < minL) minL = l;
+    }
+    return taRec({ is_high_fractal: ch === maxH, is_low_fractal: cl === minL });
+  }
+
+  /** ATR stop around chart close. Non-positive ATR → na (`_builtin_ta_atr_stop`). */
+  atrStop(close: Cell, atr: Cell, multiplier: number): TaRecord {
+    const c = finiteCell(close);
+    const a = finiteCell(atr);
+    const m = Number.isFinite(multiplier) ? multiplier : 2;
+    if (c === null || a === null || a <= 0) return taRec({ long_stop: null, short_stop: null });
+    return taRec({ long_stop: finiteOut(c - a * m), short_stop: finiteOut(c + a * m) });
+  }
+
+  /**
+   * Zigzag tuple `(high, low, direction)`. `_expect_list` materializes
+   * newest-first history, so `[-2:]` is the two oldest finite samples
+   * (PineSeries cap 1000), not the last two bars.
+   */
+  zigzag(site: string, source: Cell, threshold: number): { high: Cell; low: Cell; dir: number } {
+    const th = Number.isFinite(threshold) ? threshold : 5;
+    let st = this.zigzagSites.get(site);
+    if (st === undefined) {
+      st = { samples: [] };
+      this.zigzagSites.set(site, st);
+    }
+    pushCap(st.samples, finiteCell(source), 1000);
+    const finite: number[] = [];
+    for (const v of st.samples) {
+      if (v !== null) finite.push(v);
+    }
+    if (finite.length < 2) return { high: null, low: null, dir: 0 };
+    const oldest = finite[0]!;
+    const second = finite[1]!;
+    const recentHigh = Math.max(oldest, second);
+    const recentLow = Math.min(oldest, second);
+    const pct = recentLow !== 0 ? ((recentHigh - recentLow) / recentLow) * 100 : 0;
+    const direction = recentHigh === oldest ? 1 : -1;
+    return { high: recentHigh, low: recentLow, dir: pct > th ? 1 : direction };
+  }
+
+  private readonly accelSites = new Map<string, Cell[]>();
+
+  /** Python `pine_expect_int`: near-integers round, other finites floor. `na` throws. */
+  private coerceTaInt(value: Cell, message: string): number {
+    if (value === null || !Number.isFinite(value)) throw new Error(`${message}. Got: na`);
+    const nearest = Math.round(value);
+    if (Math.abs(value - nearest) <= PERIOD_INT_EPS) return nearest;
+    return Math.floor(value);
+  }
+
+  /**
+   * Current-bar hammer / doji (`patterns.py` `_hammer`). Both flags can be
+   * true; strength prefers doji. `na` OHLC raises (Python `TypeError`).
+   */
+  hammer(open: Cell, high: Cell, low: Cell, close: Cell): TaRecord {
+    if (open === null || high === null || low === null || close === null) {
+      throw new Error("bad operand type for abs(): 'NoneType'");
+    }
+    const body = Math.abs(close - open);
+    const range = high - low;
+    const lower = Math.min(open, close) - low;
+    const upper = high - Math.max(open, close);
+    const isDoji = body < range * 0.1;
+    const isHammer = body > 0 && lower > body * 2 && upper < body;
+    let strength = 0;
+    if (isDoji) strength = 1 - body / (range + 0.0001);
+    else if (isHammer) strength = Math.min(1, lower / (range + 0.0001));
+    return taRec({
+      is_hammer: isHammer,
+      is_doji: isDoji,
+      pattern_strength: Number.isFinite(strength) ? strength : null,
+    });
+  }
+
+  /**
+   * Gap vs an explicit prev-close scalar (`patterns.py` `_gap_detector`).
+   * `na` prev-close is the missing-scalar sentinel (zeros), not an error.
+   * Numeric prev with `na` high/low raises, matching Python arithmetic.
+   */
+  gapDetector(high: Cell, low: Cell, prevClose: Cell): TaRecord {
+    const none = taRec({ gap_size: 0, gap_type: 0, gap_percent: 0 });
+    if (prevClose === null) return none;
+    if (high === null || low === null) {
+      throw new Error("unsupported operand type(s) for -: 'float' and 'NoneType'");
+    }
+    const upside = Math.max(0, low - prevClose);
+    const downside = Math.max(0, prevClose - high);
+    if (upside > downside) {
+      const pct = prevClose !== 0 ? (upside / prevClose) * 100 : 0;
+      return taRec({
+        gap_size: upside,
+        gap_type: 1,
+        gap_percent: Number.isFinite(pct) ? pct : null,
+      });
+    }
+    if (downside > 0) {
+      const pct = prevClose !== 0 ? (downside / prevClose) * 100 : 0;
+      return taRec({
+        gap_size: downside,
+        gap_type: -1,
+        gap_percent: Number.isFinite(pct) ? pct : null,
+      });
+    }
+    return none;
+  }
+
+  /** `macd_line - signal_line` (`oscillators.py`). Either `na` → `na`. */
+  macdSignal(macdLine: Cell, signalLine: Cell): Cell {
+    if (macdLine === null || signalLine === null) return null;
+    return finiteOut(macdLine - signalLine);
+  }
+
+  /**
+   * `advanced.py` `_builtin_ta_acceleration_factor` (wins over economics).
+   * `_expect_list` is newest-first PineSeries history, cap 1000, so
+   * `[-period-1:]` is the oldest window — the value sticks once warm.
+   */
+  accelerationFactor(site: string, source: Cell, period: Cell): Cell {
+    const p = this.coerceTaInt(period, "ta.acceleration_factor() requires 2 arguments");
+    let samples = this.accelSites.get(site);
+    if (samples === undefined) {
+      samples = [];
+      this.accelSites.set(site, samples);
+    }
+    pushCap(samples, finiteCell(source), 1000);
+    if (samples.length < p + 1 || p <= 0) return 0;
+    const oldest = samples.slice(0, p + 1);
+    const newestFirst: number[] = [];
+    for (let i = oldest.length - 1; i >= 0; i--) {
+      const v = oldest[i];
+      if (v !== null) newestFirst.push(v);
+    }
+    if (newestFirst.length < 2) return 0;
+    let oldSum = 0;
+    for (let i = 0; i < newestFirst.length - 1; i++) oldSum += newestFirst[i]!;
+    const oldMom = oldSum / (newestFirst.length - 1);
+    if (Math.abs(oldMom) < 1e-10) return 0;
+    const newMom = newestFirst[newestFirst.length - 1]!;
+    let acc = (newMom - oldMom) / oldMom;
+    if (acc < -2) acc = -2;
+    if (acc > 2) acc = 2;
+    return finiteOut(acc);
+  }
+
+  /**
+   * Bar mode sees a 1-element OHLC list (`oscillators.py` `_builtin_ta_stoch_smooth`).
+   * Raw %K is the current bar; `_ema` is `na` unless both smooth lengths are 1.
+   * Period `<= 0` makes `max()` of an empty window raise.
+   */
+  stochSmooth(high: Cell, low: Cell, close: Cell, period: Cell, smoothK: Cell, smoothD: Cell): Cell {
+    const p = this.coerceTaInt(period, "ta.stoch_smooth period must be integer");
+    const k = this.coerceTaInt(smoothK, "ta.stoch_smooth smooth_k must be integer");
+    const d = this.coerceTaInt(smoothD, "ta.stoch_smooth smooth_d must be integer");
+    if (p <= 0) throw new Error("max() iterable argument is empty");
+    if (high === null || low === null || close === null) {
+      throw new Error("unsupported operand type(s) for /: 'float' and 'NoneType'");
+    }
+    if (k !== 1 || d !== 1) return null;
+    const span = high - low;
+    const stoch = span !== 0 ? (100 * (close - low)) / span : 50;
+    return finiteOut(stoch);
+  }
+
+  /**
+   * Bar-mode OHLC is a PineSeries, not a list (`len < 2`). Sentinel every bar
+   * (`patterns.py` `_builtin_ta_engulfing`) — a lookback port would disagree.
+   */
+  engulfing(): TaRecord {
+    return taRec({ is_bullish: false, is_bearish: false, pattern_strength: 0 });
+  }
+
+  /** Same one-element series: `advanced.py` `_builtin_ta_inside_bar_pattern` is always false. */
+  insideBarPattern(): boolean {
+    return false;
+  }
+
+  /**
+   * One-element high/low never fills the window (`patterns.py`
+   * `_builtin_ta_double_top_bottom`). Any finite period is the none-sentinel;
+   * `na` period still raises.
+   */
+  doubleTopBottom(period: Cell): TaRecord {
+    if (period === null || !Number.isFinite(period)) {
+      throw new Error("period must be integer. Got: na");
+    }
+    return taRec({ pattern_type: "none", strength: 0, breakout_level: 0 });
+  }
+
+  // `_expect_list` materializes PineSeries history newest-first (cap 1000).
+  // Negative indexes are the oldest samples, not the latest bars.
+  private readonly cumDeltaSites = new Map<string, { close: Cell[]; volume: Cell[] }>();
+  private readonly volMomSites = new Map<string, { volume: Cell[] }>();
+  private readonly volProfileLowSites = new Map<string, { close: Cell[]; volume: Cell[] }>();
+  private readonly volThrustSites = new Map<string, { close: Cell[]; volume: Cell[]; sma: Cell[] }>();
+
+  private asCount(value: number): number | null {
+    if (!Number.isFinite(value)) return null;
+    const nearest = Math.round(value);
+    return Math.abs(value - nearest) <= PERIOD_INT_EPS ? nearest : Math.floor(value);
+  }
+
+  private pushChrono(buf: Cell[], value: Cell): void {
+    buf.push(value !== null && Number.isFinite(value) ? value : null);
+    if (buf.length > 1000) buf.shift();
+  }
+
+  /** Newest-first negative index into a chronological buffer. */
+  private nf(buf: Cell[], i: number): Cell {
+    const v = buf[-i - 1];
+    return v === undefined ? null : v;
+  }
+
+  /** `ta.voi` — non-numeric inputs are 0 (`volume.py`). */
+  voi(buy: Cell, sell: Cell): Cell {
+    const b = buy !== null && Number.isFinite(buy) ? buy : 0;
+    const s = sell !== null && Number.isFinite(sell) ? sell : 0;
+    const total = b + s;
+    if (total === 0) return 0;
+    return finiteOut((b - s) / total);
+  }
+
+  /** `ta.bid_ask_imbalance` — `{imbalance_ratio, spread}` (`volume.py`). */
+  bidAskImbalance(bidSize: Cell, askSize: Cell, bidPrice: Cell, askPrice: Cell): TaRecord {
+    const bid = bidSize !== null && Number.isFinite(bidSize) ? bidSize : 0;
+    const ask = askSize !== null && Number.isFinite(askSize) ? askSize : 0;
+    const bidPx = bidPrice !== null && Number.isFinite(bidPrice) ? bidPrice : 0;
+    const askPx = askPrice !== null && Number.isFinite(askPrice) ? askPrice : 0;
+    const total = bid + ask;
+    if (total === 0) return taRec({ imbalance_ratio: 0, spread: 0 });
+    return taRec({
+      imbalance_ratio: finiteOut((bid - ask) / total),
+      spread: finiteOut(bidPx > 0 ? askPx - bidPx : 0),
+    });
+  }
+
+  /** `ta.rsi_oversold_overbought` — current sample only (`oscillators.py`). */
+  rsiOversoldOverbought(rsi: Cell, oversold: number, overbought: number): TaRecord {
+    if (rsi === null || !Number.isFinite(rsi)) {
+      return taRec({ is_oversold: false, is_overbought: false, rsi: null });
+    }
+    const os = this.asCount(oversold);
+    const ob = this.asCount(overbought);
+    if (os === null || ob === null) {
+      return taRec({ is_oversold: false, is_overbought: false, rsi });
+    }
+    return taRec({ is_oversold: rsi < os, is_overbought: rsi > ob, rsi });
+  }
+
+  /**
+   * `ta.rsi_divergence` — last element of the list Python returns.
+   * A scalar is a one-element series (`i < period` → 0). Do not accumulate.
+   */
+  rsiDivergence(series: Cell[], period: number): Cell {
+    const p = this.asCount(period);
+    if (p === null || series.length === 0) return null;
+    let last = 0;
+    for (let i = 0; i < series.length; i++) {
+      if (i < p) {
+        last = 0;
+        continue;
+      }
+      const start = Math.max(0, i - p);
+      const vals: number[] = [];
+      for (let j = start; j <= i; j++) {
+        const v = series[j];
+        if (v !== null && Number.isFinite(v)) vals.push(v);
+      }
+      if (vals.length < 2) {
+        last = 0;
+        continue;
+      }
+      let rsiMin = vals[0]!;
+      let rsiMax = vals[0]!;
+      for (const v of vals) {
+        if (v < rsiMin) rsiMin = v;
+        if (v > rsiMax) rsiMax = v;
+      }
+      const cur = series[i];
+      const range = rsiMax - rsiMin;
+      if (cur === null || !Number.isFinite(cur) || range <= 0) {
+        last = 0;
+        continue;
+      }
+      last = ((cur - rsiMin) / range) * 2 - 1;
+    }
+    return finiteOut(last);
+  }
+
+  /** `ta.cumulative_delta` — oldest `period` bars (`advanced.py`). */
+  cumulativeDelta(site: string, close: Cell, volume: Cell, period: number): Cell {
+    const n = this.asCount(period);
+    let st = this.cumDeltaSites.get(site);
+    if (st === undefined) {
+      st = { close: [], volume: [] };
+      this.cumDeltaSites.set(site, st);
+    }
+    this.pushChrono(st.close, close);
+    this.pushChrono(st.volume, volume);
+    if (n === null || n <= 0 || st.close.length < n || st.volume.length < n) return 0;
+    let delta = 0;
+    for (let i = -n; i < 0; i++) {
+      const cRaw = this.nf(st.close, i);
+      const vRaw = this.nf(st.volume, i);
+      const c = cRaw !== null && Number.isFinite(cRaw) ? cRaw : 0;
+      const v = vRaw !== null && Number.isFinite(vRaw) ? vRaw : 0;
+      if (i > -n) {
+        const prevRaw = this.nf(st.close, i - 1);
+        const prev = prevRaw !== null && Number.isFinite(prevRaw) ? prevRaw : c;
+        if (c > prev) delta += v;
+        else if (c < prev) delta -= v;
+      }
+    }
+    return finiteOut(delta);
+  }
+
+  /** `ta.volume_momentum` — oldest `period + 1` volumes (`advanced.py`). */
+  volumeMomentum(site: string, volume: Cell, period: number): Cell {
+    const n = this.asCount(period);
+    let st = this.volMomSites.get(site);
+    if (st === undefined) {
+      st = { volume: [] };
+      this.volMomSites.set(site, st);
+    }
+    this.pushChrono(st.volume, volume);
+    if (n === null || n <= 0 || st.volume.length < n + 1) return 0;
+    const clean: number[] = [];
+    for (let i = 0; i < n + 1; i++) {
+      const v = st.volume[i];
+      if (v !== null && Number.isFinite(v)) clean.push(v);
+    }
+    if (clean.length < 2) return 0;
+    const newVol = clean[0]!;
+    let sum = 0;
+    for (let i = 1; i < clean.length; i++) sum += clean[i]!;
+    const oldVol = sum / (clean.length - 1);
+    if (oldVol === 0) return 0;
+    let momentum = ((newVol - oldVol) / oldVol) * 100;
+    if (momentum > 100) momentum = 100;
+    if (momentum < -100) momentum = -100;
+    return finiteOut(momentum);
+  }
+
+  /**
+   * `ta.volume_profile_high` — numeric list only (`advanced.py`).
+   * A one-element pair is that price when its volume is the strict max.
+   */
+  volumeProfileHigh(prices: Cell[], volumes: Cell[]): Cell {
+    if (prices.length === 0 || volumes.length === 0 || prices.length !== volumes.length) return 0;
+    let maxVol = 0;
+    let maxPrice = 0;
+    for (let i = 0; i < prices.length; i++) {
+      const v = volumes[i];
+      if (v === null || !Number.isFinite(v) || !(v > maxVol)) continue;
+      maxVol = v;
+      const p = prices[i];
+      maxPrice = p !== null && Number.isFinite(p) ? p : 0;
+    }
+    return finiteOut(maxPrice);
+  }
+
+  /** `ta.volume_profile_low` — buckets over the oldest `period` pairs (`advanced.py`). */
+  volumeProfileLow(site: string, close: Cell, volume: Cell, period: number, levels: number): Cell {
+    const p = this.asCount(period);
+    const lv = this.asCount(levels);
+    let st = this.volProfileLowSites.get(site);
+    if (st === undefined) {
+      st = { close: [], volume: [] };
+      this.volProfileLowSites.set(site, st);
+    }
+    this.pushChrono(st.close, close);
+    this.pushChrono(st.volume, volume);
+    const oldest = st.close.length > 0 ? st.close[0]! : null;
+    const fallback: Cell = st.close.length === 0 ? 100 : oldest !== null && Number.isFinite(oldest) ? oldest : null;
+    if (p === null || lv === null || p <= 0 || lv <= 0 || st.close.length < p) return fallback;
+    const prices: number[] = [];
+    const vols: number[] = [];
+    for (let i = -p; i < 0; i++) {
+      const c = this.nf(st.close, i);
+      const v = this.nf(st.volume, i);
+      if (c !== null && Number.isFinite(c) && v !== null && Number.isFinite(v)) {
+        prices.push(c);
+        vols.push(v);
+      }
+    }
+    if (prices.length === 0) return fallback;
+    let minP = prices[0]!;
+    let maxP = prices[0]!;
+    for (const c of prices) {
+      if (c < minP) minP = c;
+      if (c > maxP) maxP = c;
+    }
+    if (minP === maxP) return minP;
+    const bucket = (maxP - minP) / lv;
+    const buckets = new Array<number>(lv).fill(0);
+    for (let k = 0; k < prices.length; k++) {
+      let idx = Math.trunc((prices[k]! - minP) / bucket);
+      if (idx > lv - 1) idx = lv - 1;
+      if (idx < 0) idx = 0;
+      buckets[idx] = (buckets[idx] ?? 0) + vols[k]!;
+    }
+    let minIdx = 0;
+    for (let i = 1; i < lv; i++) {
+      if ((buckets[i] ?? 0) < (buckets[minIdx] ?? 0)) minIdx = i;
+    }
+    return finiteOut(minP + minIdx * bucket);
+  }
+
+  /**
+   * `ta.volume_thrust` — bool as 1/0. `[-1]`/`[-2]` are the oldest two
+   * samples (`advanced.py`), not the current bar.
+   */
+  volumeThrust(site: string, close: Cell, volume: Cell, volSma: Cell, sensitivity: number): Cell {
+    const sens = Number.isFinite(sensitivity) ? sensitivity : 0.3;
+    let st = this.volThrustSites.get(site);
+    if (st === undefined) {
+      st = { close: [], volume: [], sma: [] };
+      this.volThrustSites.set(site, st);
+    }
+    this.pushChrono(st.close, close);
+    this.pushChrono(st.volume, volume);
+    this.pushChrono(st.sma, volSma);
+    if (st.close.length === 0 || st.volume.length === 0 || st.sma.length === 0) return 0;
+    const numOr = (v: Cell, fallback: number): number => (v !== null && Number.isFinite(v) ? v : fallback);
+    const cVal = numOr(this.nf(st.close, -1), 100);
+    const cPrev = st.close.length > 1 ? numOr(this.nf(st.close, -2), 100) : 100;
+    const vVal = numOr(this.nf(st.volume, -1), 1000);
+    const vsVal = numOr(this.nf(st.sma, -1), 1000);
+    const spike = vVal > vsVal * (1 + sens);
+    const move = cPrev !== 0 ? Math.abs(cVal - cPrev) / cPrev > 0.01 : false;
+    return spike && move ? 1 : 0;
+  }
+}
+
+/** Spearman rho. Rank is the stable sort position (`_rci_spearman`). */
+function spearmanRho(vals: number[]): Cell {
+  const n = vals.length;
+  if (n < 2) return null;
+  const order = vals.map((_, i) => i);
+  order.sort((i, j) => vals[i]! - vals[j]!);
+  let d2 = 0;
+  for (let pos = 0; pos < n; pos++) {
+    const d = order[pos]! - pos;
+    d2 += d * d;
+  }
+  const denom = n * (n * n - 1);
+  if (denom === 0) return null;
+  return finiteOut(1 - (6 * d2) / denom);
 }