kestrel.markets/dist/series/windows.d.ts

A typed, token-efficient language + runtime for agentic trading: agents author bounded plans, the runtime fires them at the tick. CLI + typed library + MCP server.

/**
 * # series/windows — window series over ring buffers + trailing baselines (RUNTIME §2)
 *
 * The magnitude/rate half of canonical state. Every rate/magnitude series carries a
 * **window** (`velocity(1m)`, `move(1w)`, `range(1d)`) and there is **no absolute shock**:
 * a value is judged against *that window's own trailing baseline* (`p99`, `3sigma`,
 * CONTEXT: Window). This file owns:
 *
 * 1. A spot **ring buffer** — the `(ts, px)` samples fed from SPOT ticks, the substrate
 *    every windowed metric reads back through (never recomputed per consumer, RUNTIME §2).
 * 2. The **three window metrics**, each with a `$/window` and a `%/window` reading:
 *    - `velocity(w)` — the **signed** change over the trailing window `spot(now) −
 *      spot(now−w)`: direction matters (a fast *up*-move). `$/window` = the signed dollar
 *      change; `%/window` = that change over the window-start price.
 *    - `move(w)` — the **magnitude** `|spot(now) − spot(now−w)|`: "how big was the move"
 *      regardless of sign (so `move(1w) > p99` catches a big move either way).
 *    - `range(w)` — the peak-to-trough **excursion** `max − min` over the trailing window.
 *    (velocity is signed, move is its unsigned magnitude — they are deliberately different
 *    series, not a duplication.)
 * 3. **Trailing baseline distributions** per (metric, window): a fixed-capacity ring of
 *    recent window-values supporting `p50/p95/p99` (nearest-rank) and `sigma` (population
 *    stddev).
 *
 * ## Warmup (UNKNOWN until warm — RUNTIME §2, documented rule)
 * - A **window metric** reads UNKNOWN until the buffer *spans* the window — i.e. there is a
 *   sample at or before `now − w`. Before that a lookback would extrapolate off the start
 *   of the buffer, so it reads UNKNOWN, never a guess.
 * - A **baseline** reads UNKNOWN until its ring holds at least `minBaselineSamples` values
 *   (default 30) — a floor for a stable tail estimate; configurable.
 *
 * ## Determinism (RUNTIME §0)
 * All time is injected via the sample `ts`; no wall clock, no RNG. A (metric, window)
 * baseline is *tracked* (its ring starts filling) from the first tick after it is
 * registered — so for byte-identical replay the driver pre-{@link WindowEngine.track}s the
 * combos referenced by the armed documents (their set is fixed a priori). Same bus + same
 * tracked set ⇒ identical baselines.
 */
import type { TimeUnit } from "../lang/index.ts";
import { type Unknown } from "./types.ts";
/** The three window metrics. `velocity` is signed; `move` is its unsigned magnitude;
 * `range` is the peak-to-trough excursion. */
export type WindowMetric = "velocity" | "move" | "range";
/** A window reading in both framings: `dollars` = the `$/window` value; `pct` = the
 * `%/window` value (a fraction, e.g. 0.012 = 1.2%). */
export interface WindowValue {
    readonly dollars: number;
    readonly pct: number;
}
/** The baseline statistic requested against a window series. `p` with `n∈[0,100]` is a
 * nearest-rank percentile; `sigma` with `n` is `n` population standard deviations above the
 * mean (the portable form of "big", CONTEXT: Window). */
export type BaselineStat = {
    readonly kind: "p";
    readonly n: number;
} | {
    readonly kind: "sigma";
    readonly n: number;
};
/** Configuration for the window engine. All optional; the defaults are documented above. */
export interface WindowConfig {
    /** Trailing samples retained per baseline ring (default 512). */
    readonly baselineCapacity?: number;
    /** Minimum baseline samples before `p*`/`sigma` warm from UNKNOWN (default 30). */
    readonly minBaselineSamples?: number;
    /** Hard cap on retained spot samples (oldest evicted beyond it; default 200_000). A
     * bounded session never approaches this — it only fences a pathological stream. */
    readonly maxSamples?: number;
}
export declare class WindowEngine {
    private readonly samples;
    private readonly baselines;
    private readonly cfg;
    constructor(cfg?: WindowConfig);
    /** Register a (metric, window) combo so its trailing baseline starts filling. Idempotent.
     * Pre-track the armed set for byte-identical replay (see file header). */
    track(metric: WindowMetric, value: number, unit: TimeUnit): void;
    /** Feed one SPOT sample (ts strictly non-decreasing — the injected clock). Appends to the
     * ring, evicts beyond `maxSamples`, then pushes the current value of every *tracked* combo
     * into its trailing baseline. */
    pushSpot(ts: number, px: number): void;
    /** The current reading of a window metric at `now`, or UNKNOWN until the buffer spans the
     * window. `now` is the injected clock (typically the latest sample's ts). */
    value(metric: WindowMetric, value: number, unit: TimeUnit, now: number): WindowValue | Unknown;
    /** The baseline statistic of a window metric, or UNKNOWN if the combo is untracked or has
     * fewer than `minBaselineSamples` trailing samples. */
    baseline(metric: WindowMetric, value: number, unit: TimeUnit, stat: BaselineStat): number | Unknown;
    /** Number of retained spot samples (test/introspection). */
    get sampleCount(): number;
    reset(): void;
    private compute;
    /** The most recent sample price at or before `cutoff`, or undefined if every sample is
     * newer than the cutoff (the buffer does not span the window ⇒ UNKNOWN). */
    private priceAtOrBefore;
    private latestPx;
}
//# sourceMappingURL=windows.d.ts.map