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.
257 lines • 12.3 kB
TypeScript
/**
* # frame/render-json — the `json` Rendering: a THIRD format adapter at the one-walk seam (ADR-0052 §2)
*
* The `json` Rendering materializes a {@link ./types.ts Kernel}/Frame into **typed, structural JSON**
* carrying every Field WHOLE — the machine-legible twin of the canonical text screen
* ({@link ./render.ts}) and the token-optimal ARM ({@link ./render-arm.ts}). Like both text adapters,
* the kernel goes through the ONE cockpit-kernel walk ({@link ./kernel-walk.ts walkKernel}): the
* {@link JsonKernelSink} is the third {@link ./kernel-walk.ts KernelSink}, visiting the SAME 8
* fixed-order sections in the SAME order, so a new/reordered kernel section lands in json from the
* single edit in `kernel-walk.ts`. This module NEVER touches canonical/ARM bytes — the renderer epoch
* corpus (canonical text + both ARMs) is unchanged; the json Rendering's byte contract is its own
* golden fixtures, not the epoch.
*
* ## The invariants this adapter lives inside (ADR-0052 §2, ADR-0009 — not up for grading)
* - **Fields cross WHOLE.** A {@link ./types.ts Field} (a predictor/regime {@link ./types.ts Claim})
* is emitted as `{ value, attribution, source?, modelVer?, confidence?, asOfSeq? }` — a `MODEL`
* Field keeps its receipt (`source` + `modelVer`) and `confidence`; an `OBS`/`CALC` value crosses as
* its raw typed value (it carries no receipt). Provenance is never invented: a raw kernel number
* (a health rate, a strike, an envelope) is NOT dressed up with a fabricated attribution.
* - **null Fields cross as explicit UNKNOWN.** An absent/`null`/non-finite value is carried as the
* explicit {@link UNKNOWN} marker — NEVER omitted, NEVER defaulted to `0`/`false`. This mirrors the
* canonical codebook (ADR-0041 §1: the `UNKNOWN` marker, never a bare `?`/omission); the whole
* point is that a reader can tell "unknown" from "absent" from "zero".
* - **Invents no value.** Every number/string is a field on the input; there is no layout to compute
* (json is structural), so a Rendering here never derives a value canonical draws (an axis bound, a
* column) — it carries the raw Fields, from which a consumer (the honest chart, ADR-0052 §3)
* computes its own view.
* - **Fail-closed honesty.** A dishonest `MODEL` claim (non-MODEL, or missing its receipt/confidence)
* is REFUSED at the seam ({@link ./types.ts assertClaimHonest}) exactly as the canonical adapter
* refuses it — a degraded claim is never serialized as if honest.
* - **Deterministic + byte-stable.** Serialization runs through the ONE canonical JSON module
* ({@link ../canonical/json.ts canonicalizeJson}: recursively ordered keys, kept array order, no
* trailing newline) — the SAME bytes the Bus/Blotter content-address, so the same Frame always
* yields byte-identical json. No wall clock, no RNG (RUNTIME §0).
*/
import type { BriefingInput, ChainRow, Claim, Field, InstrumentSpec, Kernel, Position, RestingOrder, SizingHeadroom, WakeDeltaInput, WakeRef } from "./types.ts";
/** The explicit unknown marker (ADR-0052 §2 / the ADR-0041 §1 codebook). An absent/`null`/non-finite
* value crosses the json wire as this literal — NEVER an omitted key (which reads as "absent") and
* NEVER a defaulted `0`/`false` (which reads as a real value). The one honest reading of a null Field. */
export declare const UNKNOWN: "UNKNOWN";
export type JsonUnknown = typeof UNKNOWN;
/** A value that may be genuinely unavailable: the value, or the explicit {@link UNKNOWN} marker. */
export type Maybe<T> = T | JsonUnknown;
/** A {@link ./types.ts Field} carried WHOLE — value + attribution, plus the `MODEL` receipt
* (`source` + `modelVer`) and `confidence` when present. A raw `OBS`/`CALC` value has no receipt. */
export interface FieldJson {
readonly value: number | string;
readonly attribution: Field["attribution"];
readonly source?: string;
readonly modelVer?: string;
readonly confidence?: number;
readonly asOfSeq?: number;
}
/** A predictor/regime claim carried WHOLE — its type + its honest `MODEL` {@link FieldJson}. */
export interface ClaimJson {
readonly claimType: Claim["claimType"];
readonly field: FieldJson;
}
export interface MandateJson {
readonly objective: string;
readonly rUsd: Maybe<number>;
readonly successCriterion: string;
readonly riskRule: string;
}
export interface BriefJson {
readonly text: string;
readonly hash: string;
readonly version?: string;
/** Labelled at the seam, exactly as the text adapters do: the Brief is directional English that can
* NEVER enter admission/narrowing (ADR-0026 hard guard) — a consumer must not read it as a constraint. */
readonly channel: "directional; NOT a constraint, NOT an admission input";
}
export interface WakeJson {
readonly reason: string;
readonly severity: WakeRef["severity"];
/** Minutes-to-close, a RELATIVE duration (date-blind); UNKNOWN when absent. Never a wall clock/date. */
readonly deadlineMinToClose: Maybe<number>;
}
export interface VehicleHealthJson {
readonly instrument: string;
readonly bidPresentRate: Maybe<number>;
readonly twoSided: boolean;
readonly staleS: Maybe<number>;
readonly dark: boolean;
}
export interface PositionJson {
readonly instrument: string;
/** An equity/spot leg carries NEITHER strike NOR right (ADR-0017) — both UNKNOWN; an option carries both. */
readonly strike: Maybe<number>;
readonly right: Maybe<Position["right"] & string>;
readonly qty: number;
readonly basis: Maybe<number>;
readonly unrealUsd: Maybe<number>;
readonly structure: Maybe<string>;
readonly claimOwner: Maybe<string>;
readonly plan: Maybe<string>;
}
export interface RestingJson {
readonly ref: string;
readonly side: RestingOrder["side"];
readonly instrument: string;
readonly strike: Maybe<number>;
readonly right: Maybe<RestingOrder["right"] & string>;
readonly qty: number;
readonly px: Maybe<number>;
readonly live: boolean;
readonly clamped: boolean;
readonly note: Maybe<string>;
}
export interface BudgetJson {
readonly remainingR: Maybe<number>;
readonly planEnvelope: Maybe<number>;
readonly bookEnvelope: Maybe<number>;
readonly ownerEnvelope: Maybe<number>;
}
export interface SizingJson {
readonly instrument: string;
readonly unit: SizingHeadroom["unit"];
readonly basisPerUnit: Maybe<number>;
readonly maxUnits: Maybe<number>;
readonly remainingUsd: Maybe<number>;
readonly note?: string;
}
export interface OwnerActJson {
readonly id: string;
readonly kind: string;
readonly asOfSeq: number;
}
/** The engine log bucketed exactly as the text adapters bucket it — the four fixed buckets in order
* plus a catch-all `other` (absent-not-hidden: a kind outside the closed union is surfaced, never dropped). */
export interface EngineActionJson {
readonly id: string;
readonly kind: string;
readonly asOfSeq: number;
readonly reason: Maybe<string>;
}
export interface EngineLogBucketJson {
readonly kind: string;
readonly count: number;
readonly actions: readonly EngineActionJson[];
}
export interface EngineLogJson {
readonly buckets: readonly EngineLogBucketJson[];
readonly other: readonly EngineActionJson[];
}
/** The cockpit kernel as typed JSON — the same 8 fixed-order sections the text adapters render, every
* section ALWAYS present (absent-not-hidden: an empty section is `[]`/explicit UNKNOWN, never omitted). */
export interface KernelJson {
readonly frame: "OPEN" | "WAKE";
readonly mandate: MandateJson | null;
readonly brief: BriefJson | null;
readonly wake: Maybe<WakeJson>;
readonly dataHealth: readonly VehicleHealthJson[];
readonly unavailable: readonly string[];
readonly positions: readonly PositionJson[];
readonly resting: readonly RestingJson[];
readonly budget: Maybe<BudgetJson>;
readonly sizing: Maybe<SizingJson>;
readonly ownerEnvelope: Maybe<number>;
readonly ownerActs: readonly OwnerActJson[];
readonly engineLog: EngineLogJson;
readonly claims: readonly ClaimJson[];
}
/**
* Materialize the cockpit kernel as typed {@link KernelJson} — the ONE walk ({@link walkKernel})
* driving the {@link JsonKernelSink}. This is the json Rendering at the walkKernel seam. PURE +
* deterministic; refuses a dishonest claim (fail-closed, {@link assertClaimHonest}).
*/
export declare function renderKernelJson(kernel: Kernel, frameKind: "OPEN" | "WAKE"): KernelJson;
export interface InstrumentJson {
readonly symbol: string;
readonly assetClass: InstrumentSpec["assetClass"];
readonly role: Maybe<string>;
readonly multiplier: Maybe<number>;
readonly tick: Maybe<number>;
}
export interface LevelsJson {
readonly spot: Maybe<number>;
readonly priorClose: Maybe<number>;
readonly hod: Maybe<number>;
readonly lod: Maybe<number>;
readonly vwap: Maybe<number>;
readonly orHigh: Maybe<number>;
readonly orLow: Maybe<number>;
}
/** One tape bucket — OHLC carried WHOLE with its HH:MM ET clock (date-blind). The honest chart draws
* candles from THESE raw numbers; an UNKNOWN never becomes an interpolated candle (ADR-0052 §3). */
export interface TapeRowJson {
readonly clock: string;
readonly open: Maybe<number>;
readonly high: Maybe<number>;
readonly low: Maybe<number>;
readonly close: Maybe<number>;
readonly volume: Maybe<number>;
}
export interface ChainRowJson {
readonly strike: Maybe<number>;
readonly right: ChainRow["right"];
/** A `null` bid/ask side is DARK — carried as explicit UNKNOWN, never a fabricated price (ADR §4). */
readonly bid: Maybe<number>;
readonly ask: Maybe<number>;
readonly fair: Maybe<number>;
readonly fairNote: Maybe<string>;
}
export interface MarketJson {
readonly instrument: string;
readonly levels: LevelsJson;
readonly tapeBucketMin: Maybe<number>;
readonly tape: readonly TapeRowJson[];
readonly chainDte: Maybe<number>;
readonly chain: readonly ChainRowJson[];
}
/** The OPEN keyframe as typed JSON. */
export interface BriefingJson {
readonly kind: "OPEN";
readonly timeToCloseMin: Maybe<number>;
readonly phase: Maybe<string>;
readonly clockET: Maybe<string>;
readonly kernel: KernelJson;
readonly instruments: readonly InstrumentJson[];
readonly market: MarketJson;
}
/** The WAKE delta frame as typed JSON. */
export interface WakeDeltaJson {
readonly kind: "WAKE";
readonly wakeIndex: number;
readonly minutesSinceLast: Maybe<number>;
readonly timeToCloseMin: Maybe<number>;
readonly phase: Maybe<string>;
readonly clockET: Maybe<string>;
readonly wakeReason: Maybe<string>;
readonly kernel: KernelJson;
readonly market: MarketJson;
}
export type FrameJson = BriefingJson | WakeDeltaJson;
/**
* Render the OPEN keyframe briefing as the typed json Rendering (ADR-0052 §2) — the kernel through
* the seam ({@link renderKernelJson}) plus the raw market/instrument Fields (the honest-chart
* substrate). Fields WHOLE, nulls explicit UNKNOWN, no value invented. Refuses a dishonest claim
* (fail-closed). PURE + deterministic.
*/
export declare function renderBriefingJson(input: BriefingInput): BriefingJson;
/**
* Render a WAKE delta frame as the typed json Rendering (ADR-0052 §2). Structural, so it carries the
* full since-last kernel + market (json is NOT the KV-cache-optimized text delta path — a consumer
* diffs structurally). Fields WHOLE, nulls explicit UNKNOWN. Refuses a dishonest claim (fail-closed).
* PURE + deterministic.
*/
export declare function renderWakeDeltaJson(input: WakeDeltaInput): WakeDeltaJson;
/**
* Serialize a json Rendering to its byte-stable canonical bytes — through the ONE canonical JSON
* module ({@link ../canonical/json.ts canonicalizeJson}: recursively ordered keys, kept array order,
* NO trailing newline), the SAME bytes the Bus/Blotter content-address. The same Frame always yields
* byte-identical text (determinism, RUNTIME §0). Deterministic + pure.
*/
export declare function serializeFrameJson(frame: FrameJson | KernelJson): string;
//# sourceMappingURL=render-json.d.ts.map