kestrel.markets/dist/protocol/grade.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.

/**
 * # protocol/grade — the one OSS-exported deterministic Judge (kestrel-h314 D4, CONTEXT "Judge")
 *
 * `grade(blotters) → GradeResult` is the deterministic grader any self-hosted Kestrel — or any outsider —
 * runs to score a SET of protocol {@link ./index.ts Blotter}s. It is the recompute substrate certification
 * rests on: it consumes ONLY the public protocol Blotter (no engine, no bus, no runtime), so the managed
 * service's signed output must be byte-identical to what this function produces from the published record.
 *
 * TWO METRIC FAMILIES, ONE GRID. Every number lands on the SAME 1e-8 rounding grid this module OWNS (NOT a
 * platform `round6`), exported as {@link REPORT_GRID} / {@link roundToGrid} so downstream report surfaces
 * round through this one primitive instead of re-declaring `1e8` (kestrel-z473.6), so a re-derivation is
 * byte-stable:
 *   • the ACTIVITY family  — `realized_pnl`, `fill_rate`, `order_count`, `fill_count`, `position_count`,
 *     `gross_traded_qty`, `filled_notional` — a pure fold of the generic order/fill/position/settlement
 *     arrays every Blotter carries; and
 *   • the RISK-HONEST family — `bankable_ev`, `realized_floor_usd`, `expected_usd` — recomputed from the
 *     CERTIFIED EVIDENCE (`totals` + `fill_claim`, kestrel-h314 D2). `bankable_ev` applies the ADR-0014
 *     banking doctrine ({@link ./support.ts bankableEvOf}) over the fill-claim partition: the calibrated
 *     slice banks in full, the extrapolated slice banks ONLY its losses.
 *
 * AGGREGATION = Σ over the set + a sorted-join on `subjectSessionId`. Grading N Blotters yields ONE
 * GradeResult whose subject identity is the members' `sessionId`s sorted and joined — deterministic and
 * order-independent (same set ⇒ same subject ⇒ same numbers).
 *
 * FAIL-CLOSED (kestrel-h314 D6). A pre-widening Blotter that lacks the certified evidence (`totals` and/or
 * `fill_claim` absent) CANNOT be certified for the risk-honest metrics: the whole family is REFUSED —
 * OMITTED from `metrics` (never a silent zero) — and a `labels.risk_honest = "unknown"` verdict names the
 * offending session(s). The activity family, which needs no evidence, still computes. UNKNOWN in, UNKNOWN
 * out; a certified number never renders without its evidence.
 */
import type { Blotter, GradeResult } from "./index.ts";
/** The Judge's OWN rounding grid (kestrel-h314 D4): a 1e-8 quantization, NOT a platform `round6`. This is
 * the SHARED report/grader $-grid — every downstream surface that rounds report dollars ({@link
 * ../blotter/project.ts}, {@link ../session/sim.ts buildReport}) imports it from here rather than
 * re-declaring `1e8` locally, so an outsider's re-derivation is byte-identical (kestrel-z473.6 re-homing).
 * A `const`, per ADR-0046 (protocol stays dependency-free — types and consts/pure fns only). */
export declare const REPORT_GRID = 100000000;
/** Quantize a report dollar onto the shared {@link REPORT_GRID}. The ONE rounding primitive the grader and
 * every downstream report surface share (kestrel-z473.6): same math everywhere ⇒ byte-identical bytes. */
export declare function roundToGrid(x: number): number;
/** Closeness tolerance for validating a NORMALIZED probability distribution sums to 1 (used by the receipt
 * validator's `day_type_probabilities` check, {@link ../grade/receipt.ts}). A DIFFERENT quantity from
 * {@link REPORT_GRID}, kept distinct on purpose (kestrel-z473.6 — re-home, never silently unify): the grid
 * is a $-quantization (1e-8), this is a dimensionless closeness bound on a unit-sum distribution, held one
 * decade tighter at 1e-9. Both live here so the divergence is named in one place, not scattered. */
export declare const PROBABILITY_SUM_TOLERANCE = 1e-9;
/**
 * The deterministic OSS Judge (kestrel-h314 D4): grade a SET of protocol Blotters into one {@link GradeResult}.
 * Pure — no wall clock, no RNG, no runtime. Same set ⇒ byte-identical result. See the module header for the
 * two metric families, the shared 1e-8 grid, the sorted-join subject identity, and the fail-closed evidence
 * gate on the risk-honest family.
 */
export declare function grade(blotters: readonly Blotter[]): GradeResult;
//# sourceMappingURL=grade.d.ts.map