kestrel.markets
Version:
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.
271 lines • 13.3 kB
TypeScript
/**
* # builders — the programmatic authoring surface (ADR-0004)
*
* Ergonomic constructors for the {@link ../ast.ts} object model. An ESM module composing
* these objects and a `.kestrel` file are the same kind of module (ADR-0004): programs
* compose here, agents/humans write text, neither is second-class.
*
* Every helper returns a plain readonly AST node with its `kind` tag filled in. Optional
* fields are omitted (never set to `undefined`) so the result satisfies
* `exactOptionalPropertyTypes`.
*/
import type { AbsolutePrice, Anchor, AnchorName, Arbitration, ArmClause, Baseline, BookStatement, Budget, CancelIfClause, Citation, Comparison, CompareOp, Coverage, Counterfactual, CrossEvent, DeliverSpec, DoTicket, Duration, ExitClause, ExpirySelector, FillEvent, GradeDimension, GradeStatement, GradeSubject, HeldQuantifier, ImportDecl, InvalidateClause, Instrument, Leg, Lean, Module, Operand, OrderPolicy, PaneArg, PaneRef, PhaseEvent, PlanClause, PlanStatement, PodStatement, PriceExpr, PriceMinMax, PriceOffset, Provenance, Quantity, RegimeGate, RegimeTagBinding, ReloadClause, RiskLine, SeriesRef, Standing, Statement, StrikeSpec, StructuralEvent, TimeOfDay, TimeUnit, TimeWindowTrig, TpClause, TpTarget, Trigger, Ttl, Using, ViewStatement, WakeBudget, WakeStatement, Window } from "./ast.ts";
export declare const win: (value: number, unit: TimeUnit) => Window;
export declare const dur: (value: number, unit: TimeUnit) => Duration;
export declare const tod: (hour: number, minute: number) => TimeOfDay;
export declare const num: (value: number, unit?: Quantity["unit"]) => Quantity;
export declare const p: (n: number) => Baseline;
export declare const sigma: (n: number) => Baseline;
/** A series reference: `series("spot")`, `series("velocity", { window: win(1,"m") })`.
* Dotted paths pass segments: `series(["regime","intraday"])`. The market/org distinction
* is registry metadata, not syntax (ADR-0004), so it is not encoded here. */
export declare function series(path: string | readonly string[], opts?: {
window?: Window;
}): SeriesRef;
/** An org-aggregate path with a quantified segment: `children(any).drawdown`. */
export declare const childrenAny: (field: string) => SeriesRef;
/** A named plan-state path: `plan(chase-urgent).state`. */
export declare const planState: (planName: string, field?: string) => SeriesRef;
export declare const cmp: (left: Operand, op: CompareOp, right: Operand) => Comparison;
export declare const gt: (l: Operand, r: Operand) => Comparison;
export declare const ge: (l: Operand, r: Operand) => Comparison;
export declare const lt: (l: Operand, r: Operand) => Comparison;
export declare const le: (l: Operand, r: Operand) => Comparison;
export declare const eq: (l: Operand, r: Operand) => Comparison;
export declare const ne: (l: Operand, r: Operand) => Comparison;
/** A cross edge event. `opts.touch` picks the at-or-touch predicate (`touches`, `>=`/`<=`);
* `opts.band` is a positive re-arm width so a lone spurious tick cannot phantom-fire.
* Both are omitted (a bare strict cross) by default. The band>0 doctrine invariant is enforced
* at construction (fail closed early) via ./validate.ts, symmetric with parse/print. */
export declare const cross: (left: Operand, direction: "above" | "below", right: Operand, opts?: {
touch?: boolean;
band?: Quantity;
}) => CrossEvent;
/** Refuse to CONSTRUCT held-over-cross (the sfg8 anti-pattern; ./validate.ts). `within` over a
* cross stays legal. */
export declare const held: (inner: Trigger, d: Duration) => Trigger;
export declare const within: (inner: Trigger, d: Duration) => Trigger;
/** `held <dur>` in lead position — a 0DTE time-held stop (`EXIT held 90m`); a bare hold-clock on
* the acquired position, NOT the `held(inner, dur)` break-hold postfix (docs/results/fomc-options).*/
export declare const heldStop: (d: Duration) => Trigger;
/** `clockET <clock>` — a 0DTE wall-clock time-stop (`EXIT clockET 15:40`). */
export declare const clockStop: (time: TimeOfDay) => Trigger;
/** `inner until <clock>` — the thesis temporal envelope (kestrel-rtf), a postfix sibling of
* `within` over the same predicate surface (no second predicate language). */
export declare const until: (inner: Trigger, time: TimeOfDay) => Trigger;
/** `inner at <clock>` — the thesis temporal envelope (kestrel-rtf), a postfix sibling of `within`. */
export declare const at: (inner: Trigger, time: TimeOfDay) => Trigger;
export declare const nth: (ordinal: number, event: Trigger) => Trigger;
export declare const event: (name: string, of?: Operand) => StructuralEvent;
export declare const phase: (name: string) => PhaseEvent;
export declare const timeWindow: (opts: {
from?: TimeOfDay;
to?: TimeOfDay;
}) => TimeWindowTrig;
export declare const fill: (evt: FillEvent["event"], leg?: number) => FillEvent;
export declare const and: (...terms: Trigger[]) => Trigger;
export declare const or: (...terms: Trigger[]) => Trigger;
export declare const not: (term: Trigger) => Trigger;
export declare const anchor: (name: AnchorName) => Anchor;
export declare const fair: Anchor;
export declare const intrinsic: Anchor;
export declare const basis: Anchor;
export declare const bid: Anchor;
export declare const ask: Anchor;
export declare const mid: Anchor;
export declare const last: Anchor;
export declare const join: Anchor;
export declare const improve: Anchor;
export declare const stub: Anchor;
export declare const spot: Anchor;
export declare const px: (value: number) => AbsolutePrice;
export declare const minus: (base: PriceExpr, amount: number, unit?: "c" | "%") => PriceOffset;
export declare const plus: (base: PriceExpr, amount: number, unit?: "c" | "%") => PriceOffset;
export declare const lean: (a: PriceExpr, b: PriceExpr, x: number) => Lean;
export declare const pmin: (...args: PriceExpr[]) => PriceMinMax;
export declare const pmax: (...args: PriceExpr[]) => PriceMinMax;
export declare const rel: (steps: number) => StrikeSpec;
export declare const abs: (strike: number) => StrikeSpec;
export declare const atm: StrikeSpec;
export declare const delta: (d: number) => StrikeSpec;
/** An option leg `buy <qty> <strike> <right>`, optionally with its OWN expiry (`buy 2 +1 C exp 0dte`,
* kestrel-ih5h seam 1). Omit `expiry` and the leg inherits the ambient `USING exec` tenor — the object
* form of leaving `exp` off the text, so the two authoring surfaces (ADR-0004: objects and text are
* peers) stay mechanically equivalent. */
export declare const buy: (qty: number, strike: StrikeSpec, right: "C" | "P", expiry?: ExpirySelector) => Leg;
export declare const sell: (qty: number, strike: StrikeSpec, right: "C" | "P", expiry?: ExpirySelector) => Leg;
/** An equity/spot leg `buy <qty> shares` (ADR-0017) — no strike/right; the symbol is the
* ambient `USING exec`. */
export declare const buyShares: (qty: number) => Leg;
export declare const sellShares: (qty: number) => Leg;
export declare const esc: (to: PriceExpr, after: Duration) => {
kind: "esc-stage";
to: PriceExpr;
after: Duration;
};
export declare const policy: (opts: {
pricing?: "peg" | "fix";
esc?: readonly ReturnType<typeof esc>[];
caps?: readonly PriceExpr[];
floors?: readonly PriceExpr[];
cancelIf?: Trigger;
gtc?: boolean;
}) => OrderPolicy;
export declare const foreachHeld: HeldQuantifier;
export declare const anyHeld: HeldQuantifier;
export declare const doTicket: (opts: {
legs: readonly Leg[];
price: PriceExpr;
policy?: OrderPolicy;
atomic?: boolean;
}) => DoTicket;
export declare const also: (opts: {
legs: readonly Leg[];
price: PriceExpr;
policy?: OrderPolicy;
atomic?: boolean;
}) => PlanClause;
export declare const reload: (opts: {
when?: Trigger;
legs: readonly Leg[];
price: PriceExpr;
policy?: OrderPolicy;
atomic?: boolean;
}) => ReloadClause;
export declare const tpPct: (pct: number) => TpTarget;
export declare const tpMult: (mult: number) => TpTarget;
export declare const tpPrice: (price: PriceExpr) => TpTarget;
export declare const tp: (opts: {
target: TpTarget;
frac?: number;
over?: HeldQuantifier;
price?: PriceExpr;
policy?: OrderPolicy;
}) => TpClause;
export declare const exit: (opts: {
when: Trigger;
over?: HeldQuantifier;
price?: PriceExpr;
policy?: OrderPolicy;
}) => ExitClause;
export declare const invalidate: (when: Trigger) => InvalidateClause;
export declare const cancelIf: (when: Trigger) => CancelIfClause;
export declare const arm: (opts?: {
when?: Trigger;
basis?: PriceExpr;
over?: HeldQuantifier;
}) => ArmClause;
export declare const dte: (n: number) => ExpirySelector;
export declare const expDate: (date: string) => ExpirySelector;
export declare const expTag: (tag: string) => ExpirySelector;
export declare const instrument: (symbol: string, expiry?: ExpirySelector) => Instrument;
export declare const using: (opts: {
signal?: Instrument;
exec?: Instrument;
}) => Using;
export declare const provenance: (opts: {
tier?: Provenance["tier"];
author?: string;
origin?: string;
replay?: string;
}) => Provenance;
/** A `because` pre-registration citation (kestrel-rtf): a content hash of the fixed shape
* `sha256:<64 hex>`, no inline body. Refuses a malformed digest at construction, symmetric with
* parse/print (./validate.ts), so the object never exists to break `parse(print(x))`. */
export declare const citation: (hash: string, algo?: Citation["algo"]) => Citation;
export declare const budget: (value: number) => Budget;
export declare const ttlIn: (d: Duration) => Ttl;
export declare const ttlAt: (at: TimeOfDay) => Ttl;
export declare const regime: (...tags: RegimeTagBinding[]) => RegimeGate;
export declare const tag: (scope: string, value: string) => RegimeTagBinding;
export declare const argIdent: (name: string) => PaneArg;
export declare const argWindow: (w: Window) => PaneArg;
export declare const argCount: (count: number) => PaneArg;
/** A SessionOrdinal literal `d-<n>` (Train 1B / ADR-0041 §1): `d-0` current session, `d-1` prior… */
export declare const argOrdinal: (ordinal: number) => PaneArg;
/** An ExpiryOrdinal literal `e-<n>` (Train 1B / ADR-0041 §1): `e-0` nearest expiry, `e-1` next out… */
export declare const argExpiry: (expiry: number) => PaneArg;
export declare const pane: (name: string, ...args: PaneArg[]) => PaneRef;
export declare const view: (name: string, panes: readonly PaneRef[], opts?: {
budget?: number;
}) => ViewStatement;
export declare const deliver: (viewName: string, opts?: {
mandatory?: boolean;
keyframe?: boolean;
}) => DeliverSpec;
export declare const wakeBudget: (opts: {
wakesPerDay?: number;
tokensPerDay?: number;
}) => WakeBudget;
export declare const wake: (name: string, when: Trigger, opts?: {
because?: Citation;
deliver?: DeliverSpec;
priority?: number;
coalesce?: string;
budget?: WakeBudget;
universe?: {
kind: "universe";
universe: string;
};
}) => WakeStatement;
export declare const universe: (name: string) => {
kind: "universe";
universe: string;
};
export declare const plan: (name: string, opts?: {
budget?: Budget;
ttl?: Ttl;
regime?: RegimeGate;
priority?: number;
standing?: Standing;
provenance?: Provenance;
using?: Using;
when?: Trigger;
because?: Citation;
clauses?: readonly PlanClause[];
atomic?: boolean;
}) => PlanStatement;
export declare const subject: (what: GradeSubject["what"], name: string) => GradeSubject;
export declare const over: (from: string, to: string) => {
kind: "corpus-range";
from: string;
to: string;
};
export declare const vsUngated: Counterfactual;
export declare const vsNull: Counterfactual;
export declare const vsBracket: Counterfactual;
export declare const bySeries: (s: SeriesRef) => GradeDimension;
export declare const byVehicle: GradeDimension;
export declare const byName: GradeDimension;
export declare const byLineage: GradeDimension;
export declare const grade: (gradeSubject: GradeSubject, opts?: {
over?: {
kind: "corpus-range";
from: string;
to: string;
};
fill?: string;
versus?: readonly Counterfactual[];
by?: readonly GradeDimension[];
}) => GradeStatement;
export declare const coverage: (instruments: readonly Instrument[], thesis: string) => Coverage;
export declare const arbitration: (policy: string, concurrency?: number) => Arbitration;
export declare const risk: (metric: string, threshold: Quantity, action: string) => RiskLine;
export declare const book: (name: string, opts?: {
budget?: Budget;
coverage?: Coverage;
arbitration?: Arbitration;
risk?: readonly RiskLine[];
}) => BookStatement;
export declare const pod: (name: string, opts?: {
risk?: readonly RiskLine[];
children?: readonly (PodStatement | BookStatement)[];
}) => PodStatement;
export declare const importFrom: (names: readonly string[], from: string) => ImportDecl;
export declare const module: (opts: {
imports?: readonly ImportDecl[];
using?: Using;
statements?: readonly Statement[];
provenance?: Provenance;
}) => Module;
//# sourceMappingURL=builders.d.ts.map