@hoox-sh/pynets 0.4.0 → 0.6.0

package/src/runtime/request.ts

@@ -9,8 +9,11 @@
  * is the host's job (`bucketIndex` / `shouldForwardFill`).
  * Lower-TF request without a feed is na — no invented intra-bar array.
  * Interpret should call this from `evalCall`; this module is host-agnostic.
+ * `request.footprint` is the Python mock (not foreign-na).
  */
 
+import { createFootprint, seedFootprintRng } from "./footprint.ts";
+
 export type Cell = number | null;
 
 export interface SecurityArgs {
@@ -29,7 +32,7 @@ export interface RequestHost {
  * Named or positional args for `resolveRequest`.
  * Security uses `symbol` / `timeframe` / `sameSymbolValue`;
  * currency uses `from`/`to` (or `from_currency`/`to_currency`);
- * seed uses `seed`.
+ * seed uses `seed`; footprint uses `num_ticks` / `va_percentage`.
  */
 export interface RequestNamedArgs {
   symbol?: string | null;
@@ -41,6 +44,8 @@ export interface RequestNamedArgs {
   from_currency?: string | null;
   to_currency?: string | null;
   seed?: unknown;
+  num_ticks?: unknown;
+  va_percentage?: unknown;
 }
 
 export type RequestArgs = readonly unknown[] | RequestNamedArgs;
@@ -231,7 +236,7 @@ function bareTicker(symbol: string): string {
   return colon >= 0 ? s.slice(colon + 1) : s;
 }
 
-/** Missing / foreign fundamentals, economic, quandl, footprint → na. */
+/** Missing / foreign fundamentals, economic, quandl → na. */
 export function resolveForeignNa(): Cell {
   return null;
 }
@@ -249,9 +254,10 @@ export function resolveCurrencyRate(
   return null;
 }
 
-/** `request.seed` — record the seed (Python returns None). */
+/** `request.seed` — record the seed and seed the footprint RNG (Python returns None). */
 export function resolveSeed(seed?: unknown): Cell {
   lastSeed = coerceSeed(seed ?? 0);
+  seedFootprintRng(lastSeed);
   return null;
 }
 
@@ -262,7 +268,7 @@ export function lastRequestSeed(): number | null {
 /**
  * Dispatch a `request.*` name. Security keeps `resolveSecurity` semantics;
  * lower-TF without a feed is na; currency is 1.0 only for identical codes;
- * everything else is na.
+ * footprint is the Python mock; everything else is na.
  */
 export function resolveRequest(
   fname: string,
@@ -284,6 +290,10 @@ export function resolveRequest(
   if (fname === "request.seed") {
     return resolveSeed(seedFromArgs(args));
   }
+  if (fname === "request.footprint") {
+    const [numTicks, va] = footprintFromArgs(args);
+    return createFootprint(numTicks, va);
+  }
   return resolveForeignNa();
 }
 
@@ -326,6 +336,11 @@ function seedFromArgs(args: RequestArgs): unknown {
   return args.seed ?? 0;
 }
 
+function footprintFromArgs(args: RequestArgs): [unknown, unknown] {
+  if (!isNamedArgs(args)) return [args[0] ?? 100, args[1] ?? 70];
+  return [args.num_ticks ?? 100, args.va_percentage ?? 70];
+}
+
 function currencyPair(
   from: string | null | undefined,
   to: string | null | undefined,

package/src/runtime/str.ts

@@ -4,6 +4,7 @@
  *
  * Pine `str.*` helpers. `null` is na.
  */
+import { timestampToMs } from "./time.ts";
 
 function asStr(x: unknown): string | null {
   if (x == null) return null;
@@ -303,8 +304,8 @@ function coerceFormatTimeMs(time: unknown): number | null {
   if (raw == null || typeof raw === "boolean" || typeof raw === "string") return null;
   if (typeof raw !== "number" || !Number.isFinite(raw)) return null;
   let ts = Math.trunc(raw);
-  // Python: 0 < timestamp < 10_000_000_000 → Unix seconds, coerce to ms.
-  if (ts > 0 && ts < 10_000_000_000) ts *= 1000;
+  // Python `utility._timestamp_to_ms`: Unix seconds (< 1e11) become ms.
+  ts = timestampToMs(ts) ?? ts;
   return ts;
 }
 

package/src/runtime/strategy.ts

@@ -30,7 +30,7 @@ export interface BrokerSettings {
 }
 
 export interface StrategyEvent {
-  type: "entry" | "close" | "exit" | "cancel" | "close_all" | "cancel_all" | "fill";
+  type: "entry" | "close" | "exit" | "cancel" | "close_all" | "cancel_all" | "fill" | "order";
   id: string;
   direction?: StrategyDirection;
   qty?: number | null;
@@ -63,11 +63,16 @@ export interface PendingOrder {
   oca_name?: string | null;
   oca_type?: OcaType;
   /** Unset on entry orders so existing pending snapshots stay exact. */
-  kind?: "entry" | "exit";
+  kind?: "entry" | "exit" | "close" | "close_all";
   from_entry?: string | null;
   trail_offset?: number | null;
   trail_activation?: number | null;
   trail_active?: boolean;
+  /** Market order queued for the next bar open (PYNE 0.6.29 `placed_bar` gate). */
+  deferred?: boolean;
+  /** `strategy.entry` target-position semantics at fill time. */
+  is_entry?: boolean;
+  comment?: string;
 }
 
 export interface PlaceEntryOpts {
@@ -79,6 +84,8 @@ export interface PlaceEntryOpts {
   time?: number;
   oca_name?: string | null;
   oca_type?: string | null;
+  /** Queue a market order for the next bar open instead of filling now. */
+  deferMarket?: boolean;
 }
 
 /** Named `strategy.exit` args (Pine: id, from_entry, qty, qty_percent, …). */
@@ -99,6 +106,8 @@ export interface PlaceExitOpts {
   time?: number;
   /** Current bar OHLC so a newly placed exit can fill same bar. */
   ohlc?: BarOhlc;
+  /** Queue a level-less market exit for the next bar open. */
+  deferMarket?: boolean;
 }
 
 /** One open or closed strategy trade (qty is absolute). */
@@ -140,6 +149,8 @@ export interface BarOhlc {
   high?: number;
   low?: number;
   close?: number;
+  /** Bar timestamp used for trade `entry_time` / `exit_time`. */
+  time?: number;
 }
 
 /** Snapshot of book-level performance scalars (for RuntimeResult). */
@@ -905,6 +916,64 @@ export class StrategyBook {
     });
   }
 
+  /**
+   * `strategy.close` — queue a market cover for the next bar open and emit
+   * the placement `close` event (PYNE 0.6.29). A flat book only emits.
+   */
+  placeClose(
+    bar: number,
+    id: string,
+    price?: number,
+    opts?: { qty?: number | null; time?: number; comment?: string },
+  ): void {
+    const b = isFiniteNumber(bar) ? bar : 0;
+    const oid = String(id ?? "");
+    this.ensureSanePosition();
+    if (this.position.qty !== 0) {
+      const absPos = Math.abs(this.position.qty);
+      const rawQty = opts?.qty;
+      const q =
+        isFiniteNumber(rawQty) && rawQty >= 0 ? Math.min(Math.abs(rawQty), absPos) : absPos;
+      if (q > 0) {
+        this.upsertPending({
+          id: `${oid}:close`,
+          direction: this.position.qty > 0 ? "short" : "long",
+          qty: q,
+          limit: null,
+          stop: null,
+          bar: b,
+          kind: "close",
+          deferred: true,
+          comment: opts?.comment,
+        });
+      }
+    }
+    this.close(b, oid);
+  }
+
+  /**
+   * `strategy.close_all` — queue a market flatten for the next bar open and
+   * emit the placement `close_all` event (PYNE 0.6.29).
+   */
+  placeCloseAll(bar: number, price?: number, opts?: { comment?: string }): void {
+    const b = isFiniteNumber(bar) ? bar : 0;
+    this.ensureSanePosition();
+    if (this.position.qty !== 0) {
+      this.upsertPending({
+        id: "close_all",
+        direction: this.position.qty > 0 ? "short" : "long",
+        qty: Math.abs(this.position.qty),
+        limit: null,
+        stop: null,
+        bar: b,
+        kind: "close_all",
+        deferred: true,
+        comment: opts?.comment,
+      });
+    }
+    this.events.push({ type: "close_all", id: "", bar: b });
+  }
+
   exit(bar: number, id: string, qty?: number | null): void {
     const event: StrategyEvent = {
       type: "exit",
@@ -949,8 +1018,9 @@ export class StrategyBook {
 
   /**
    * Place an entry. No limit/stop → market via fillEntry (needs `opts.price`).
-   * Otherwise records a pending order. Always emits an `entry` event
-   * (market path emits it through fillEntry).
+   * With `deferMarket`, a market entry is queued and fills at the next bar
+   * open (PYNE 0.6.29 reference-Pine flow). Otherwise records a pending
+   * limit/stop order. Always emits a placement event.
    */
   placeEntry(
     bar: number,
@@ -961,10 +1031,44 @@ export class StrategyBook {
   ): void {
     const limit = optLevel(opts?.limit);
     const stop = optLevel(opts?.stop);
+    const b = isFiniteNumber(bar) ? bar : 0;
+    const oid = String(id ?? "");
     if (limit == null && stop == null) {
+      if (opts?.deferMarket === true) {
+        const dir = mapDirection(direction);
+        const absQty = isFiniteNumber(qty) ? Math.abs(qty) : Number.NaN;
+        if (!isFiniteNumber(absQty) || absQty <= 0) return;
+        const t = isFiniteNumber(opts?.time) ? opts.time : b;
+        if (!this.riskAllowsEntry(dir, t)) return;
+        const mark = isFiniteNumber(opts?.price) ? opts.price : 0;
+        const capped = this.capQtyByMaxPosition(absQty, mark);
+        if (!isFiniteNumber(capped) || capped <= 0) return;
+        // Same-direction add gate (PYNE pyramiding cap = pyramiding + 1).
+        const signed = dir === "long" ? capped : -capped;
+        if (this.position.qty !== 0 && Math.sign(this.position.qty) === Math.sign(signed)) {
+          const maxEntries = this.pyramiding !== undefined ? this.pyramiding + 1 : 1;
+          const allowed =
+            this.pyramiding !== undefined && this.pyramiding > 0 && this.opentrades < maxEntries;
+          if (!allowed) return;
+        }
+        this.upsertPending({
+          id: oid,
+          direction: dir,
+          qty: capped,
+          limit: null,
+          stop: null,
+          bar: b,
+          kind: "entry",
+          is_entry: true,
+          deferred: true,
+          comment: opts?.comment,
+        });
+        this.events.push({ type: "order", id: oid, direction: dir, qty: capped, bar: b });
+        return;
+      }
       if (isFiniteNumber(opts?.price)) {
         const dir = mapDirection(direction);
-        const t = isFiniteNumber(opts?.time) ? opts.time : bar;
+        const t = isFiniteNumber(opts?.time) ? opts.time : b;
         this.updateEquityExtremes(opts.price);
         if (!this.riskAllowsEntry(dir, t)) return;
         this.fillEntry(bar, id, direction, qty, opts.price, opts);
@@ -973,8 +1077,6 @@ export class StrategyBook {
     }
     const dir = mapDirection(direction);
     const absQty = isFiniteNumber(qty) ? Math.abs(qty) : Number.NaN;
-    const b = isFiniteNumber(bar) ? bar : 0;
-    const oid = String(id ?? "");
     this.entry(b, oid, dir, isFiniteNumber(absQty) ? absQty : qty);
     if (!isFiniteNumber(absQty) || absQty === 0) return;
     const pending: PendingOrder = { id: oid, direction: dir, qty: absQty, limit, stop, bar: b };
@@ -1043,6 +1145,23 @@ export class StrategyBook {
 
     const t = isFiniteNumber(opts?.time) ? opts.time : b;
     if (limitP == null && stopP == null && !hasTrail) {
+      if (opts?.deferMarket === true) {
+        const closeDir: StrategyDirection = isLong ? "short" : "long";
+        this.upsertPending({
+          id: `${oid}:close`,
+          direction: closeDir,
+          qty,
+          limit: null,
+          stop: null,
+          bar: b,
+          kind: "exit",
+          from_entry: fromEntry,
+          deferred: true,
+          comment: opts?.comment,
+        });
+        this.events.push({ type: "order", id: oid, direction: closeDir, qty, bar: b });
+        return;
+      }
       if (!isFiniteNumber(opts?.price)) return;
       this.reducePosition(b, oid, opts.price, qty, fromEntry, t, opts?.comment);
       return;
@@ -1132,14 +1251,26 @@ export class StrategyBook {
     const filled: string[] = [];
     for (const order of this.pending.slice()) {
       if (!this.pending.some((p) => p.id === order.id)) continue;
+      // Reference Pine: an order placed during bar N becomes active for bar
+      // N+1 — never fills on its own placement bar.
+      if (order.bar === b) continue;
       if (order.kind === "exit" && isTrailOrder(order)) updateTrailStop(order, high, low);
-      const px = triggerPrice(order, open, high, low);
+      let px: number | null;
+      if (order.limit == null && order.stop == null) px = open;
+      else px = triggerPrice(order, open, high, low);
       if (px == null) continue;
       this.dropPending(order.id);
+      const emitEntry = order.kind === "entry" || order.deferred === true;
+      const barTime = isFiniteNumber(ohlc.time) ? ohlc.time : undefined;
       const applied =
         order.kind === "exit"
-          ? this.applyExitFill(b, order, px)
-          : this.applyEntryFill(b, order.id, order.direction, order.qty, px, false);
+          ? this.applyExitFill(b, order, px, barTime)
+          : order.kind === "close" || order.kind === "close_all"
+            ? this.applyCloseFill(b, order, px, barTime)
+            : this.applyEntryFill(b, order.id, order.direction, order.qty, px, emitEntry, {
+                comment: order.comment,
+                time: barTime,
+              });
       if (applied) {
         const q = Math.abs(this.fills.at(-1)?.qty ?? order.qty);
         this.ocaAfterFill(order, q, b);
@@ -1156,6 +1287,27 @@ export class StrategyBook {
     return filled;
   }
 
+  /** Apply a queued market close/close_all at the next bar open. */
+  private applyCloseFill(
+    bar: number,
+    order: PendingOrder,
+    price: number,
+    time?: number,
+  ): boolean {
+    this.ensureSanePosition();
+    if (this.position.qty === 0 || !isFiniteNumber(price)) return false;
+    const absPos = Math.abs(this.position.qty);
+    const rawQty = order.qty;
+    const q = isFiniteNumber(rawQty) && rawQty > 0 ? Math.min(Math.abs(rawQty), absPos) : absPos;
+    if (!(q > 0)) return false;
+    if (q < absPos - 1e-12) {
+      this.reducePosition(bar, order.id, price, q, order.from_entry ?? null, time, order.comment);
+    } else {
+      this.flattenAt(bar, order.id, price, time, order.comment);
+    }
+    return true;
+  }
+
   /** Market entry at `price`. Flat/same-dir adds qty; opposite closes then reverses. */
   fillEntry(
     bar: number,
@@ -1302,9 +1454,9 @@ export class StrategyBook {
     return { status: "ok", qty: Math.min(rawQty, target) };
   }
 
-  private applyExitFill(bar: number, order: PendingOrder, price: number): boolean {
+  private applyExitFill(bar: number, order: PendingOrder, price: number, time?: number): boolean {
     const t = isFiniteNumber(bar) ? bar : 0;
-    return this.reducePosition(t, order.id, price, order.qty, order.from_entry ?? null, t);
+    return this.reducePosition(t, order.id, price, order.qty, order.from_entry ?? null, time);
   }
 
   private closeLeg(