@hoox-sh/pynets 0.1.0

package/src/runtime/library.ts

@@ -0,0 +1,282 @@
+/**
+ * Copyright (C) 2024-2026 jango_blockchained
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * In-process Pine library registry for export/import resolution.
+ */
+
+export type StubKwargs = Record<string, unknown>;
+export type StubExportFn = (...args: unknown[]) => unknown;
+
+export type LibraryLookup = {
+  namespace?: string | null;
+  name: string;
+  version?: number | null;
+};
+
+export type LibraryModuleInit = {
+  namespace?: string | null;
+  version?: number | null;
+  exports?: Map<string, unknown> | Record<string, unknown>;
+};
+
+function isPlainObject(value: unknown): value is StubKwargs {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/** Best-effort int for stub polyfills; null / non-numeric → null. */
+function coerceStubInt(value: unknown): number | null {
+  if (value == null) return null;
+  if (typeof value === "boolean") return value ? 1 : 0;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) return null;
+    return Math.trunc(value);
+  }
+  if (typeof value === "bigint") {
+    const n = Number(value);
+    if (!Number.isFinite(n)) return null;
+    return Math.trunc(n);
+  }
+  if (typeof value === "string") {
+    const t = value.trim();
+    if (!/^[+-]?\d+$/.test(t)) return null;
+    const n = Number(t);
+    if (!Number.isFinite(n)) return null;
+    return Math.trunc(n);
+  }
+  return null;
+}
+
+/** Merge positional + keyword args into a dense list using `order` names. */
+function mergeStubArgs(args: unknown[], kwargs: StubKwargs, order: string[]): unknown[] {
+  const merged: unknown[] = args.slice();
+  for (const [key, val] of Object.entries(kwargs)) {
+    const idx = order.indexOf(key);
+    if (idx < 0) continue;
+    while (merged.length <= idx) merged.push(null);
+    if (idx < args.length && args[idx] != null) continue;
+    merged[idx] = val;
+  }
+  return merged;
+}
+
+function parseStubCall(
+  callArgs: unknown[],
+  kwargs?: StubKwargs,
+): { args: unknown[]; kwargs: StubKwargs } {
+  if (kwargs !== undefined) return { args: callArgs, kwargs };
+  if (callArgs.length === 0) return { args: [], kwargs: {} };
+  if (callArgs.length === 1 && isPlainObject(callArgs[0])) {
+    return { args: [], kwargs: callArgs[0] };
+  }
+  if (
+    Array.isArray(callArgs[0]) &&
+    (callArgs.length === 1 || callArgs.length === 2) &&
+    (callArgs[1] === undefined || isPlainObject(callArgs[1]))
+  ) {
+    return { args: callArgs[0], kwargs: callArgs[1] ?? {} };
+  }
+  const last = callArgs[callArgs.length - 1];
+  if (callArgs.length > 1 && isPlainObject(last)) {
+    return { args: callArgs.slice(0, -1), kwargs: last };
+  }
+  return { args: callArgs, kwargs: {} };
+}
+
+function stubIndex2dTo1d(args: unknown[], kwargs: StubKwargs): number | null {
+  const order = ["dimension_x", "dimension_y", "index_x", "index_y"];
+  const alias: Record<string, string> = {
+    dim_x: "dimension_x",
+    dim_y: "dimension_y",
+    ix: "index_x",
+    iy: "index_y",
+  };
+  const norm: StubKwargs = {};
+  for (const [k, v] of Object.entries(kwargs)) norm[alias[k] ?? k] = v;
+  const vals = mergeStubArgs(args, norm, order);
+  if (vals.length < 4) return null;
+  const dy = coerceStubInt(vals[1]);
+  const ix = coerceStubInt(vals[2]);
+  const iy = coerceStubInt(vals[3]);
+  if (dy == null || ix == null || iy == null) return null;
+  return ix * dy + iy;
+}
+
+function stubIndex1dTo2d(args: unknown[], kwargs: StubKwargs): [number, number] | null {
+  const order = ["dimension_x", "dimension_y", "index"];
+  const alias: Record<string, string> = {
+    dim_x: "dimension_x",
+    dim_y: "dimension_y",
+    i: "index",
+  };
+  const norm: StubKwargs = {};
+  for (const [k, v] of Object.entries(kwargs)) norm[alias[k] ?? k] = v;
+  const vals = mergeStubArgs(args, norm, order);
+  if (vals.length < 3) return null;
+  const dy = coerceStubInt(vals[1]);
+  const idx = coerceStubInt(vals[2]);
+  if (dy == null || idx == null || dy === 0) return null;
+  const ix = Math.floor(idx / dy);
+  const iy = ((idx % dy) + dy) % dy;
+  return [ix, iy];
+}
+
+/** Row-major flatten: `index_x * dimension_y + index_y`. */
+export function index_2d_to_1d(...args: unknown[]): number | null {
+  const parsed = parseStubCall(args);
+  return stubIndex2dTo1d(parsed.args, parsed.kwargs);
+}
+
+/** Inverse of `index_2d_to_1d` → `[index_x, index_y]`. */
+export function index_1d_to_2d(...args: unknown[]): [number, number] | null {
+  const parsed = parseStubCall(args);
+  return stubIndex1dTo2d(parsed.args, parsed.kwargs);
+}
+
+/** Known export polyfills for unresolved remote libraries (import stubs). */
+export const STUB_KNOWN_EXPORTS: Record<string, StubExportFn> = {
+  index_2d_to_1d,
+  index_1d_to_2d,
+};
+
+/** Call a known stub by export name with positional + named args. */
+export function applyStubExport(
+  name: string,
+  args: unknown[] = [],
+  kwargs: StubKwargs = {},
+): unknown {
+  if (name === "index_2d_to_1d") return stubIndex2dTo1d(args, kwargs);
+  if (name === "index_1d_to_2d") return stubIndex1dTo2d(args, kwargs);
+  const fn = STUB_KNOWN_EXPORTS[name];
+  if (fn == null) return undefined;
+  return fn(args, kwargs);
+}
+
+function toExportMap(exports?: Map<string, unknown> | Record<string, unknown>): Map<string, unknown> {
+  if (exports == null) return new Map();
+  if (exports instanceof Map) return exports;
+  return new Map(Object.entries(exports));
+}
+
+export type LibraryExportKind = "const" | "fn" | "type" | "enum" | "method";
+
+/** A loaded library: title/path identity plus exported callables and values. */
+export class LibraryModule {
+  title: string;
+  namespace: string | null;
+  version: number | null;
+  exports: Map<string, unknown>;
+  kinds: Map<string, LibraryExportKind>;
+  private readonly resolveStubs: boolean;
+
+  constructor(title: string, init?: LibraryModuleInit & { resolveStubs?: boolean }) {
+    this.title = title;
+    this.namespace = init?.namespace ?? null;
+    this.version = init?.version ?? null;
+    this.exports = toExportMap(init?.exports);
+    this.kinds = new Map();
+    this.resolveStubs = init?.resolveStubs === true;
+  }
+
+  get(name: string): unknown {
+    if (this.exports.has(name)) return this.exports.get(name);
+    if (this.resolveStubs && Object.hasOwn(STUB_KNOWN_EXPORTS, name)) {
+      return STUB_KNOWN_EXPORTS[name];
+    }
+    return undefined;
+  }
+
+  has(name: string): boolean {
+    if (this.exports.has(name)) return true;
+    return this.resolveStubs && Object.hasOwn(STUB_KNOWN_EXPORTS, name);
+  }
+
+  /** Put `value` into `exports` and tag as a const. */
+  setExport(name: string, value: unknown): void {
+    this.putExport(name, value, "const");
+  }
+
+  exportType(name: string, value: unknown): void {
+    this.putExport(name, value, "type");
+  }
+
+  exportEnum(name: string, value: unknown): void {
+    this.putExport(name, value, "enum");
+  }
+
+  exportFn(name: string, value: unknown): void {
+    this.putExport(name, value, "fn");
+  }
+
+  kindOf(name: string): string | undefined {
+    const tagged = this.kinds.get(name);
+    if (tagged !== undefined) return tagged;
+    if (this.resolveStubs && Object.hasOwn(STUB_KNOWN_EXPORTS, name)) return "fn";
+    return undefined;
+  }
+
+  /** Shallow copy of stored exports (does not include unresolved stub polyfills). */
+  allExports(): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    for (const [key, value] of this.exports) out[key] = value;
+    return out;
+  }
+
+  private putExport(name: string, value: unknown, kind: LibraryExportKind): void {
+    this.exports.set(name, value);
+    this.kinds.set(name, kind);
+  }
+}
+
+/** Stub module whose known ArrayExtension helpers resolve via `STUB_KNOWN_EXPORTS`. */
+export function createStubModule(title: string): LibraryModule {
+  return new LibraryModule(title, { resolveStubs: true });
+}
+
+function pathKey(namespace: string, name: string, version: number): string {
+  return `${namespace}\0${name}\0${Math.trunc(version)}`;
+}
+
+/** Maps library identity (path and/or title) → `LibraryModule`. */
+export class LibraryRegistry {
+  private readonly byPath = new Map<string, LibraryModule>();
+  private readonly byTitle = new Map<string, LibraryModule>();
+  private readonly sources = new Map<string, string>();
+
+  /** Register or replace a loaded library (by title and path when known). */
+  register(module: LibraryModule): void {
+    this.byTitle.set(module.title, module);
+    if (module.namespace != null && module.version != null) {
+      this.byPath.set(pathKey(module.namespace, module.title, module.version), module);
+    }
+  }
+
+  /** Store Pine source for lazy load on `import namespace/name/version`. */
+  registerSource(namespace: string, name: string, version: number, source: string): void {
+    this.sources.set(pathKey(namespace, name, Math.trunc(version)), source);
+  }
+
+  /** Return registered source text, or `null` if unknown. */
+  getSource(namespace: string, name: string, version: number): string | null {
+    return this.sources.get(pathKey(namespace, name, Math.trunc(version))) ?? null;
+  }
+
+  /** Resolve by `(namespace, name, version)` path first, then by title. */
+  lookup(query: LibraryLookup): LibraryModule | null {
+    const { namespace, name, version } = query;
+    if (namespace != null && version != null) {
+      const mod = this.byPath.get(pathKey(namespace, name, version));
+      if (mod != null) return mod;
+    }
+    return this.byTitle.get(name) ?? null;
+  }
+
+  /** Drop all path, title, and source entries (tests). */
+  clear(): void {
+    this.byPath.clear();
+    this.byTitle.clear();
+    this.sources.clear();
+  }
+}

package/src/runtime/log.ts

@@ -0,0 +1,69 @@
+/**
+ * Copyright (C) 2024-2026 jango_blockchained
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * Pine `log.*` buffer (Python `Logger` SoT).
+ */
+
+export type LogLevel = "INFO" | "WARNING" | "ERROR";
+
+export interface LogRecord {
+  level: LogLevel;
+  bar: number;
+  message: string;
+}
+
+export class LogBook {
+  readonly records: LogRecord[] = [];
+
+  info(bar: number, message: string): void {
+    this.records.push({ level: "INFO", bar, message });
+  }
+
+  warning(bar: number, message: string): void {
+    this.records.push({ level: "WARNING", bar, message });
+  }
+
+  error(bar: number, message: string): void {
+    this.records.push({ level: "ERROR", bar, message });
+  }
+
+  /** Drop all records (Python `Logger.clear`). */
+  clear(): void {
+    this.records.length = 0;
+  }
+
+  /** Copy of records (Python `Logger.get_logs`). */
+  snapshot(): LogRecord[] {
+    return this.records.slice();
+  }
+}
+
+/** Pine `runtime.error` abort (Python `RuntimeError`). */
+export class RuntimeError extends Error {
+  override readonly name = "RuntimeError";
+
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+/** Halt with `RuntimeError` (Python `runtime_error`). */
+export function runtimeError(message: string): never {
+  throw new RuntimeError(message);
+}
+
+export function formatLogParts(parts: unknown[]): string {
+  if (parts.length === 0) return "";
+  const first = parts[0];
+  if (typeof first === "string" && parts.length > 1 && /\{[0-9]/.test(first)) {
+    return first.replace(/\{(\d+)\}/g, (_, i) => pineLogArg(parts[Number(i) + 1]));
+  }
+  return parts.map(pineLogArg).join(" ");
+}
+
+function pineLogArg(value: unknown): string {
+  if (value == null) return "na";
+  if (typeof value === "number" && !Number.isFinite(value)) return "na";
+  return String(value);
+}

package/src/runtime/map.ts

@@ -0,0 +1,85 @@
+/**
+ * Copyright (C) 2024-2026 jango_blockchained
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * Tiny Pine `map.*` value. Keys are string or finite number; `null` is `na`.
+ * Backed by `Map` (never a plain object) so user keys cannot pollute prototypes.
+ */
+export type Cell = number | null;
+export type MapKey = string | number;
+
+function keyOf(key: unknown): string | null {
+  if (typeof key === "string") return `s:${key}`;
+  if (typeof key === "number" && Number.isFinite(key)) {
+    const n = Object.is(key, -0) ? 0 : key;
+    return `n:${n}`;
+  }
+  return null;
+}
+
+function decodeKey(k: string): MapKey {
+  return k.startsWith("s:") ? k.slice(2) : Number(k.slice(2));
+}
+
+export class PineMap {
+  private readonly data = new Map<string, Cell>();
+  private readonly order: string[] = [];
+
+  size(): number {
+    return this.data.size;
+  }
+
+  put(key: unknown, value: Cell): void {
+    const k = keyOf(key);
+    if (k == null) return;
+    if (!this.data.has(k)) this.order.push(k);
+    this.data.set(k, value);
+  }
+
+  get(key: unknown): Cell {
+    const k = keyOf(key);
+    if (k == null) return null;
+    return this.data.has(k) ? this.data.get(k)! : null;
+  }
+
+  contains(key: unknown): boolean {
+    const k = keyOf(key);
+    return k != null && this.data.has(k);
+  }
+
+  remove(key: unknown): Cell {
+    const k = keyOf(key);
+    if (k == null || !this.data.has(k)) return null;
+    const v = this.data.get(k)!;
+    this.data.delete(k);
+    const i = this.order.indexOf(k);
+    if (i >= 0) this.order.splice(i, 1);
+    return v;
+  }
+
+  clear(): void {
+    this.data.clear();
+    this.order.length = 0;
+  }
+
+  keys(): MapKey[] {
+    return this.order.map(decodeKey);
+  }
+
+  values(): Cell[] {
+    return this.order.map((k) => this.data.get(k)!);
+  }
+
+  copy(): PineMap {
+    const out = new PineMap();
+    for (const k of this.order) out.put(decodeKey(k), this.data.get(k)!);
+    return out;
+  }
+
+  putAll(other: PineMap): void {
+    if (!(other instanceof PineMap)) return;
+    const keys = other.keys();
+    const values = other.values();
+    for (let i = 0; i < keys.length; i++) this.put(keys[i]!, values[i]!);
+  }
+}

package/src/runtime/math.ts

@@ -0,0 +1,231 @@
+/**
+ * Copyright (C) 2024-2026 jango_blockchained
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * Pine `math.*` scalars (Python `NumericBuiltinsMixin` SoT).
+ * `null` is `na`. Non-finite in/out is `na`.
+ */
+
+export type Cell = number | null;
+
+function finite(value: Cell): number | null {
+  return value !== null && Number.isFinite(value) ? value : null;
+}
+
+function finiteOut(value: number): Cell {
+  return Number.isFinite(value) ? value : null;
+}
+
+/** Half away from 0 (Pine `math.round` ties). */
+function roundHalfAwayFromZero(x: number): number {
+  return x >= 0 ? Math.round(x) : -Math.round(-x);
+}
+
+export function mathAbs(x: Cell): Cell {
+  const n = finite(x);
+  return n === null ? null : Math.abs(n);
+}
+
+/** `-1`, `0`, or `1`. */
+export function mathSign(x: Cell): Cell {
+  const n = finite(x);
+  if (n === null) return null;
+  if (n > 0) return 1;
+  if (n < 0) return -1;
+  return 0;
+}
+
+/** `na` if `x < 0`. */
+export function mathSqrt(x: Cell): Cell {
+  const n = finite(x);
+  if (n === null || n < 0) return null;
+  return finiteOut(Math.sqrt(n));
+}
+
+/** Natural log, or log base `base` when given; `na` if `x <= 0` (or base <= 0). */
+export function mathLog(x: Cell, base?: Cell): Cell {
+  const n = finite(x);
+  if (n === null || n <= 0) return null;
+  if (base === undefined) return finiteOut(Math.log(n));
+  const b = finite(base);
+  if (b === null || b <= 0 || b === 1) return null;
+  return finiteOut(Math.log(n) / Math.log(b));
+}
+
+/** `na` if `x <= 0`. */
+export function mathLog10(x: Cell): Cell {
+  const n = finite(x);
+  if (n === null || n <= 0) return null;
+  return finiteOut(Math.log10(n));
+}
+
+export function mathExp(x: Cell): Cell {
+  const n = finite(x);
+  return n === null ? null : finiteOut(Math.exp(n));
+}
+
+export function mathPow(base: Cell, exp: Cell): Cell {
+  const b = finite(base);
+  const e = finite(exp);
+  if (b === null || e === null) return null;
+  // JS `Math.pow` yields NaN for e.g. (-1)**0.5; map that (and Inf) to na.
+  return finiteOut(Math.pow(b, e));
+}
+
+/** `na` if any arg is `na` or the list is empty. */
+export function mathMax(...xs: Cell[]): Cell {
+  if (xs.length === 0) return null;
+  let max = -Infinity;
+  for (const x of xs) {
+    const n = finite(x);
+    if (n === null) return null;
+    if (n > max) max = n;
+  }
+  return finiteOut(max);
+}
+
+/** `na` if any arg is `na` or the list is empty. */
+export function mathMin(...xs: Cell[]): Cell {
+  if (xs.length === 0) return null;
+  let min = Infinity;
+  for (const x of xs) {
+    const n = finite(x);
+    if (n === null) return null;
+    if (n < min) min = n;
+  }
+  return finiteOut(min);
+}
+
+export function mathRound(x: Cell, precision?: Cell): Cell {
+  const n = finite(x);
+  if (n === null) return null;
+  if (precision === undefined) return roundHalfAwayFromZero(n);
+  const p = finite(precision);
+  if (p === null) return null;
+  const factor = 10 ** Math.trunc(p);
+  if (!Number.isFinite(factor)) return null;
+  return finiteOut(roundHalfAwayFromZero(n * factor) / factor);
+}
+
+export function mathFloor(x: Cell): Cell {
+  const n = finite(x);
+  return n === null ? null : Math.floor(n);
+}
+
+export function mathCeil(x: Cell): Cell {
+  const n = finite(x);
+  return n === null ? null : Math.ceil(n);
+}
+
+/** Arithmetic mean; `na` if any arg is `na` or the list is empty. */
+export function mathAvg(...xs: Cell[]): Cell {
+  if (xs.length === 0) return null;
+  let sum = 0;
+  for (const x of xs) {
+    const n = finite(x);
+    if (n === null) return null;
+    sum += n;
+  }
+  return finiteOut(sum / xs.length);
+}
+
+export function mathSum(...xs: Cell[]): Cell {
+  if (xs.length === 0) return null;
+  let sum = 0;
+  for (const x of xs) {
+    const n = finite(x);
+    if (n === null) return null;
+    sum += n;
+  }
+  return finiteOut(sum);
+}
+
+function trig(x: Cell, fn: (n: number) => number): Cell {
+  const n = finite(x);
+  return n === null ? null : finiteOut(fn(n));
+}
+
+export function mathSin(x: Cell): Cell {
+  return trig(x, Math.sin);
+}
+
+export function mathCos(x: Cell): Cell {
+  return trig(x, Math.cos);
+}
+
+export function mathTan(x: Cell): Cell {
+  return trig(x, Math.tan);
+}
+
+export function mathAsin(x: Cell): Cell {
+  const n = finite(x);
+  if (n === null || n < -1 || n > 1) return null;
+  return finiteOut(Math.asin(n));
+}
+
+export function mathAcos(x: Cell): Cell {
+  const n = finite(x);
+  if (n === null || n < -1 || n > 1) return null;
+  return finiteOut(Math.acos(n));
+}
+
+export function mathAtan(x: Cell): Cell {
+  return trig(x, Math.atan);
+}
+
+export function mathToDegrees(x: Cell): Cell {
+  const n = finite(x);
+  return n === null ? null : finiteOut((n * 180) / Math.PI);
+}
+
+export function mathToRadians(x: Cell): Cell {
+  const n = finite(x);
+  return n === null ? null : finiteOut((n * Math.PI) / 180);
+}
+
+/** `na` in → `na`. Else 1 if finite, 0 otherwise. */
+export function mathIsFinite(x: Cell): Cell {
+  if (x === null) return null;
+  return Number.isFinite(x) ? 1 : 0;
+}
+
+/** Default mintick 0.01 when the host does not supply one. */
+export function mathRoundToMintick(x: Cell, mintick: Cell = 0.01): Cell {
+  const n = finite(x);
+  const tick = finite(mintick);
+  if (n === null || tick === null || tick <= 0) return n === null ? null : finiteOut(Number(n.toFixed(8)));
+  return finiteOut(Math.round(n / tick) * tick);
+}
+
+/** Pine v4 `iff(cond, then, else)`. `na` condition → `na`. */
+export function mathIff(cond: Cell, thenV: Cell, elseV: Cell): Cell {
+  if (cond === null || !Number.isFinite(cond)) return null;
+  return cond ? thenV : elseV;
+}
+
+/**
+ * Python `_builtin_fixnan`: None / NaN → 0 (not prior-bar carry).
+ * Other non-finite (`Inf`) is treated as na → 0.
+ */
+export function mathFixnan(x: Cell): Cell {
+  if (x === null || !Number.isFinite(x)) return 0;
+  return x;
+}
+
+/**
+ * Uniform random. No args → [0, 1). One arg → [0, max]. Two args → [min, max]
+ * via `lo + (hi - lo) * u` (Python `random.uniform`). Any na / non-finite → na.
+ * `rng` is a [0, 1) source (default `Math.random`).
+ */
+export function mathRandom(a?: Cell, b?: Cell, rng: () => number = Math.random): Cell {
+  if (a === undefined && b === undefined) return finiteOut(rng());
+  if (b === undefined) {
+    const hi = finite(a as Cell);
+    if (hi === null) return null;
+    return finiteOut(hi * rng());
+  }
+  const lo = finite(a as Cell);
+  const hi = finite(b);
+  if (lo === null || hi === null) return null;
+  return finiteOut(lo + (hi - lo) * rng());
+}