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.
643 lines (637 loc) • 23.8 kB
JavaScript
import {
DISARM_CONTROL_TYPE
} from "./bin-mn7wcxhv.js";
import {
sha256
} from "./bin-8pchjxn2.js";
import {
groupPlanInstances,
serializeBus
} from "./bin-73jr945c.js";
import {
CORPUS_TIERS,
FACES,
partition,
roundToGrid
} from "./bin-3ft0k1jq.js";
// src/grade/headline.ts
function sampledQualified(e) {
const reasons = [];
if (!e.sampledArmed) {
reasons.push("sampled channel off (no fillSeed) — nothing to qualify (fail-closed, ADR-0016 §5)");
}
const q = e.qualification;
if (q === undefined) {
reasons.push("no sampled-channel qualification on record — calibration + causality + fidelity study not passed (kestrel-9gu.8.6; 9gu.8 AC#7, fail-closed)");
} else {
if (!q.calibration)
reasons.push("qualification leg 'calibration' not passed (kestrel-9gu.8.6)");
if (!q.causality)
reasons.push("qualification leg 'causality' not passed (kestrel-9gu.8.6)");
if (!q.fidelity)
reasons.push("qualification leg 'fidelity' not passed (kestrel-9gu.8.6)");
if (q.reference.length === 0) {
reasons.push("qualification claim carries no reference — approval provenance unstated (fail-closed)");
}
}
if (e.sampledExtrapolated) {
reasons.push("a sampled realization rests on extrapolated support — never an uncalibrated headline (bankableEv, ADR-0016 §5)");
}
return { qualified: reasons.length === 0, reasons };
}
function selectHeadline(channels, gate, taintReasons) {
const useSampled = gate.qualified && channels.sampled !== undefined;
return {
channel: useSampled ? "sampled" : "floor",
usd: useSampled ? channels.sampled : channels.floor,
gate,
tainted: taintReasons.length > 0,
reasons: [...taintReasons]
};
}
function nakedShortTaint(legs) {
const net = new Map;
const flagged = new Set;
const reasons = [];
for (const leg of legs) {
const after = (net.get(leg.key) ?? 0) + (leg.side === "buy" ? leg.qty : -leg.qty);
net.set(leg.key, after);
if (after < 0 && !flagged.has(leg.key)) {
flagged.add(leg.key);
reasons.push(`net-naked short at ${leg.key}: filled position went to ${after} (an uncovered short) — never-naked forbids this from headlining as a clean win (kestrel-22j.4)`);
}
}
return reasons;
}
function readSampledQualificationClaim(raw) {
if (typeof raw !== "object" || raw === null)
return;
const r = raw;
if (typeof r.calibration !== "boolean")
return;
if (typeof r.causality !== "boolean")
return;
if (typeof r.fidelity !== "boolean")
return;
if (typeof r.reference !== "string" || r.reference.length === 0)
return;
return { calibration: r.calibration, causality: r.causality, fidelity: r.fidelity, reference: r.reference };
}
// src/blotter/model-registry.ts
var MODEL_KNOWLEDGE_CUTOFF = {
"acme-lm-1": "2025-10",
"acme-lm-2": "2025-10",
"claude-haiku-4-5": "2025-02"
};
function isPostCutoff(cutoffMonth, tapeDate) {
return tapeDate.slice(0, 7) > cutoffMonth;
}
function checkTrainingCutoff(input) {
const { model, declaredCutoff } = input;
const registry = MODEL_KNOWLEDGE_CUTOFF[model];
if (registry === undefined) {
return {
ok: false,
reason: {
kind: "unknown-model-id",
model,
declared: declaredCutoff,
detail: `training_cutoff: model id '${model}' is not in the MODEL_KNOWLEDGE_CUTOFF registry — the declared cutoff ` + `'${declaredCutoff}' cannot be verified; the row is not treated as post- or pre-cutoff (fail-closed, kestrel-m9i.23). ` + `REMEDY: run the Knowledge-Horizon Eval (kestrel-cf62) and register an 'empirically-bounded' cutoff source ` + `(see registerEmpiricalBound / docs/research/knowledge-horizon-eval.md)`
}
};
}
if (registry !== declaredCutoff) {
return {
ok: false,
reason: {
kind: "declared-registry-mismatch",
model,
declared: declaredCutoff,
registry,
detail: `training_cutoff: declared '${declaredCutoff}' disagrees with the registry cutoff '${registry}' for model id ` + `'${model}' — the declared value is recorded, never rewritten to the registry's (fail-closed, kestrel-m9i.23)`
}
};
}
return { ok: true, cutoffMonth: registry };
}
// src/blotter/project.ts
var round = roundToGrid;
var EXCERPT_CAP = 120;
function excerptOf(body) {
let first = "";
for (const line of body.split(`
`)) {
const t = line.trim();
if (t.length > 0) {
first = t;
break;
}
}
if (first.length <= EXCERPT_CAP)
return first;
return first.slice(0, EXCERPT_CAP - 1) + "…";
}
var UNSTATED_LIMITS = [
{ code: "observability-unstated", note: "fill model declared no self-limitation; the judge's observability limits are unstated — treat all fills as maximally limited (fail-closed)" }
];
function selfLimitationOf(fillModel) {
const limits = fillModel.self_limitation ?? UNSTATED_LIMITS;
return { fill_model: fillModel.name, limits: limits.map((l) => ({ code: l.code, note: l.note })) };
}
function requireGradedMeta(bus) {
const meta = bus.find((e) => e.stream === "META");
if (meta === undefined) {
throw new Error("blotter: no META header in bus (a well-formed bus opens with exactly one META, ADR-0011)");
}
if (meta.fill_model === undefined || meta.instance === undefined || meta.fidelity === undefined) {
throw new Error("blotter: META lacks judge identity (fill_model/instance/fidelity) — the projector requires a GRADED bus, " + "not a fill-model-agnostic input tape (the two-bus rule, ADR-0011; fail-closed)");
}
return meta;
}
var REQUIRED_ENVELOPE_IDENTITY = [
"provider",
"model",
"version",
"training_cutoff",
"prompt_hash",
"tokenizer",
"tool_policy",
"rendering_identity",
"wake_source",
"token_accounting",
"corpus_tier",
"face",
"adapter",
"adapter_version"
];
function isFiniteNumber(v) {
return typeof v === "number" && Number.isFinite(v);
}
function readTokenAccounting(v) {
if (typeof v !== "object" || v === null)
return;
const r = v;
const input = r.input;
const output = r.output;
const thinking = r.thinking;
if (!isFiniteNumber(input) || !isFiniteNumber(output) || !isFiniteNumber(thinking))
return;
return { input, output, thinking };
}
function projectExperimentalEnvelope(raw) {
if (raw === undefined)
return { reasons: [] };
if (typeof raw !== "object" || raw === null) {
return {
reasons: ["envelope: declared but not an object — no required identity field can be resolved (fail-closed, a57.14)"]
};
}
const rec = raw;
const reasons = [];
const tokenAccounting = readTokenAccounting(rec.token_accounting);
for (const field of REQUIRED_ENVELOPE_IDENTITY) {
if (field === "token_accounting") {
if (tokenAccounting === undefined) {
reasons.push("envelope: missing required identity field 'token_accounting' (injected accounting absent or malformed) — fail-closed, not defaulted (a57.14)");
}
continue;
}
const v = rec[field];
if (typeof v !== "string" || v.length === 0) {
reasons.push(`envelope: missing required identity field '${field}' — fail-closed, not defaulted (a57.14)`);
continue;
}
if (field === "face" && !FACES.includes(v)) {
reasons.push(`envelope: face '${v}' is outside the closed interface vocabulary (http|sdk|cli|mcp) — fail-closed, not coerced (m9i.2)`);
}
if (field === "corpus_tier" && !CORPUS_TIERS.includes(v)) {
reasons.push(`envelope: corpus_tier '${v}' is outside the closed corpus vocabulary (public|semi-private|private) — fail-closed, not coerced (m9i.26)`);
}
}
if (reasons.length > 0)
return { reasons };
const envelope = {
provider: rec.provider,
model: rec.model,
version: rec.version,
training_cutoff: rec.training_cutoff,
prompt_hash: rec.prompt_hash,
tokenizer: rec.tokenizer,
tool_policy: rec.tool_policy,
rendering_identity: rec.rendering_identity,
wake_source: rec.wake_source,
token_accounting: tokenAccounting,
corpus_tier: rec.corpus_tier,
face: rec.face,
adapter: rec.adapter,
adapter_version: rec.adapter_version
};
return { envelope, reasons: [] };
}
function project(bus) {
const meta = requireGradedMeta(bus);
const envelopeProjection = projectExperimentalEnvelope(meta.envelope);
const envelopeReasons = [...envelopeProjection.reasons];
const cutoffCheck = envelopeProjection.envelope === undefined ? undefined : checkTrainingCutoff({
model: envelopeProjection.envelope.model,
declaredCutoff: envelopeProjection.envelope.training_cutoff
});
if (cutoffCheck !== undefined && !cutoffCheck.ok)
envelopeReasons.push(cutoffCheck.reason.detail);
const output = bus.filter((e) => e !== meta);
const session = {
instance: meta.instance,
instruments: meta.instruments,
bus: {
events: bus.length,
sha256: sha256(serializeBus(bus)),
schema: meta.bus_schema
},
determinism_hash: sha256(serializeBus(output)),
fill_model: meta.fill_model,
fidelity: {
level: meta.fidelity,
self_limitation: selfLimitationOf(meta.fill_model)
},
...envelopeProjection.envelope !== undefined ? { envelope: envelopeProjection.envelope } : {},
...typeof meta.config_id === "string" && meta.config_id.length > 0 ? { config_id: meta.config_id } : {},
...typeof meta.cell_config_id === "string" && meta.cell_config_id.length > 0 ? { cell_config_id: meta.cell_config_id } : {}
};
const journals = [];
for (const e of bus) {
if (e.stream !== "JOURNAL")
continue;
const j = e;
journals.push({ seq: j.seq, kind: j.kind, ts: j.ts, body: j.body });
}
const disarms = [];
for (const e of bus) {
if (e.stream !== "CONTROL" || e.type !== DISARM_CONTROL_TYPE)
continue;
disarms.push({ seq: e.seq, ts: e.ts, ...e.note !== undefined ? { reason: e.note } : {} });
}
const authorJournals = journals.filter((j) => j.kind === "author").sort((a, b) => a.seq - b.seq);
const reasoningRefFor = (firstPlanSeq) => {
let ref;
for (const j of authorJournals) {
if (j.seq < firstPlanSeq)
ref = j;
else
break;
}
return ref === undefined ? undefined : { seq: ref.seq, excerpt: excerptOf(ref.body) };
};
const plans = groupPlanInstances(bus).map((g) => {
const lifecycle = g.events.map((pe) => ({
seq: pe.seq,
ts: pe.ts,
state: pe.state,
...pe.outcome !== undefined ? { outcome: pe.outcome } : {},
...pe.reason !== undefined ? { reason: pe.reason } : {}
}));
const last = lifecycle[lifecycle.length - 1];
const final_state = last.outcome ?? last.state;
const ref = reasoningRefFor(lifecycle[0].seq);
return { plan: g.plan, plan_instance: g.instance, lifecycle, final_state, ...ref !== undefined ? { reasoning_ref: ref } : {} };
});
const escByRef = new Map;
const repriceByRef = new Map;
const settleByRef = new Map;
const guardByRef = new Map;
for (const e of bus) {
if (e.stream !== "TELEMETRY")
continue;
if (e.type === "order") {
const t = e;
escByRef.set(t.order_id, t.esc_stage);
if (t.reprice)
repriceByRef.set(t.order_id, (repriceByRef.get(t.order_id) ?? 0) + 1);
} else if (e.type === "settle") {
const t = e;
settleByRef.set(t.order_id, t);
} else if (e.type === "guard") {
const t = e;
guardByRef.set(t.order_id, t);
}
}
const accByRef = new Map;
const refOrder = [];
for (const e of bus) {
if (e.stream !== "ORDER")
continue;
const oe = e;
if (oe.type === "place") {
if (!accByRef.has(oe.order_id)) {
accByRef.set(oe.order_id, { place: oe, final_state: "working", filled: false });
refOrder.push(oe.order_id);
}
continue;
}
const acc = accByRef.get(oe.order_id);
if (acc === undefined)
continue;
if (oe.type === "fill") {
acc.filled = true;
acc.final_state = "filled";
} else if (oe.type === "reject") {
acc.final_state = "rejected";
if (oe.reason !== undefined)
acc.reason = oe.reason;
} else if (oe.type === "cancel") {
if (!acc.filled)
acc.final_state = oe.reason === "expired-unfilled" ? "expired" : "cancelled";
if (oe.reason !== undefined)
acc.reason = oe.reason;
}
}
const orders = refOrder.map((ref) => {
const acc = accByRef.get(ref);
const p = acc.place;
const settle = settleByRef.get(ref);
const guard = guardByRef.get(ref);
const filled = settle?.floor_filled ?? acc.filled;
const support = settle?.support ?? "calibrated";
return {
order_id: p.order_id,
...p.plan !== undefined ? { plan: p.plan } : {},
...p.plan_instance !== undefined ? { plan_instance: p.plan_instance } : {},
instrument: p.instrument,
side: p.side,
qty: p.qty,
...p.strike !== undefined ? { strike: p.strike } : {},
...p.right !== undefined ? { right: p.right } : {},
px: round(p.px ?? 0),
esc_stage: escByRef.get(ref) ?? 0,
reprice_count: repriceByRef.get(ref) ?? 0,
final_state: acc.final_state,
filled,
pFill: round(settle?.expected_fill_prob ?? (filled ? 1 : 0)),
support,
floor_pnl: round(settle?.floor_pnl ?? 0),
expected_pnl: round(settle?.expected_pnl ?? 0),
...acc.reason !== undefined ? { reason: acc.reason } : {},
...guard !== undefined ? { moneyness: guard.moneyness, covered: guard.covered, directional_cap: guard.directional_cap } : {}
};
});
let floorSum = 0;
let expectedSum = 0;
let calibratedExpected = 0;
let extrapolatedExpected = 0;
let calibratedOrders = 0;
let extrapolatedOrders = 0;
let sampledSum = 0;
let sampledArmed = false;
let sampledExtrapolated = false;
const taintReasons = [];
const claimCells = [];
let settleMarkEv;
for (const e of bus) {
if (e.stream !== "TELEMETRY")
continue;
if (e.type === "settle_mark") {
settleMarkEv = e;
continue;
}
if (e.type === "theta_bleed") {
floorSum += e.floor_pnl;
continue;
}
if (e.type !== "settle")
continue;
const s = e;
floorSum += s.floor_pnl;
expectedSum += s.expected_pnl;
if (s.sampled_pnl !== undefined) {
sampledArmed = true;
sampledSum += s.sampled_pnl;
if (s.sampled_filled === true && s.support !== "calibrated")
sampledExtrapolated = true;
}
claimCells.push({ support: s.support, ev: s.expected_pnl });
if (s.support === "calibrated") {
calibratedExpected += s.expected_pnl;
calibratedOrders += 1;
} else {
extrapolatedExpected += s.expected_pnl;
extrapolatedOrders += 1;
if (s.expected_pnl !== 0)
taintReasons.push(`${s.order_id}: expected banked on extrapolated support`);
}
}
const settle_mark = settleMarkEv === undefined ? undefined : {
px: settleMarkEv.px,
as_of_ts: settleMarkEv.as_of_ts ?? null,
last_observed_ts: settleMarkEv.last_observed_ts ?? null,
age_ms: settleMarkEv.age_ms ?? null,
stale_after_ms: settleMarkEv.stale_after_ms,
stale: settleMarkEv.stale,
source: settleMarkEv.source,
mark_uncertain: settleMarkEv.mark_uncertain,
note: settleMarkEv.note ?? null
};
if (settle_mark !== undefined && settle_mark.stale) {
const staleness = settle_mark.age_ms === null ? `settle mark ${settle_mark.px} has unstated provenance (no spot observation on the tape)` : `settle mark ${settle_mark.px} is stale: value last established ${settle_mark.age_ms}ms before settle (> ${settle_mark.stale_after_ms}ms threshold)`;
taintReasons.push(settle_mark.source === "parity" ? `${staleness}; recovered via closing put-call parity (annotated recovery) — P&L settled against it is non-bankable (kestrel-xwf)` : settle_mark.mark_uncertain ? `${staleness}; settle mark uncertain — no closing put-call parity derivable, last-known mark retained — P&L settled against it is non-bankable (kestrel-xwf, fail-closed)` : `${staleness} — P&L settled against it is non-bankable (kestrel-xwf)`);
}
const totalsFloor = round(floorSum);
const totalsExpected = round(expectedSum);
const totalsSampled = sampledArmed ? round(sampledSum) : undefined;
const qualification = readSampledQualificationClaim(meta.sampled_qualification);
const gate = sampledQualified({
sampledArmed,
sampledExtrapolated,
...qualification !== undefined ? { qualification } : {}
});
const selected = selectHeadline({ floor: totalsFloor, expected: totalsExpected, ...totalsSampled !== undefined ? { sampled: totalsSampled } : {} }, gate, taintReasons);
const headline = {
channel: selected.channel,
usd: selected.usd,
gate: selected.gate,
tainted: selected.tainted,
reasons: selected.reasons
};
const totals = {
floor: totalsFloor,
expected: totalsExpected,
...totalsSampled !== undefined ? { sampled: totalsSampled } : {},
headline,
...settle_mark !== undefined ? { settle_mark } : {}
};
const part = partition(claimCells);
const calibratedClaim = round(calibratedExpected);
const extrapolatedClaim = round(totalsExpected - calibratedClaim);
const calibratedGain = round(part.calibrated.gain);
const extrapolatedGain = round(part.extrapolated.gain);
const fill_claim = [
{
support: "calibrated",
orders: calibratedOrders,
expected: calibratedClaim,
gain: calibratedGain,
loss: round(calibratedClaim - calibratedGain)
},
{
support: "extrapolated",
orders: extrapolatedOrders,
expected: extrapolatedClaim,
gain: extrapolatedGain,
loss: round(extrapolatedClaim - extrapolatedGain)
}
];
const certification = certificationOf(session.instance.mode, envelopeReasons);
const rankability = deriveRankability({
certification,
cutoffCheck,
sessionDate: meta.session_date,
dateBlind: meta.date_blind,
seasonFrozen: meta.season_frozen,
clockHonest: meta.clock_honest
});
const deliberations = [];
for (const e of bus) {
if (e.stream !== "WAKE" || e.type !== "deliberation")
continue;
deliberations.push({
seq: e.seq,
wake_seq: e.wake_seq,
ts: e.ts,
measured_ms: e.measured_ms,
buffer_ms: e.buffer_ms
});
}
const wake_trace = deliberations.length > 0 ? {
deliberations,
deliberation_ms_total: deliberations.reduce((s, d) => s + d.measured_ms + d.buffer_ms, 0)
} : undefined;
return {
session,
certification,
rankability,
journals,
disarms,
plans,
orders,
totals,
fill_claim,
...wake_trace !== undefined ? { wake_trace } : {}
};
}
function certificationOf(mode, envelopeReasons) {
const isSim = mode === "sim";
const legs = {
determinism: "pass",
detectors_bit_for_bit: "na",
fills_subset_of_live: "na",
lifecycle_divergence_explained: "na"
};
if (envelopeReasons.length > 0) {
return { legs, verdict: "provisional", reasons: envelopeReasons };
}
return { legs, verdict: isSim ? "certified" : "provisional" };
}
function attestationLeg(v) {
if (v === true)
return "pass";
if (v === false)
return "fail";
return "unknown";
}
function deriveRankability(input) {
const reasons = [];
const certified = input.certification.verdict === "certified" ? "pass" : "fail";
if (certified === "fail") {
reasons.push({
kind: "not-certified",
detail: "rankable: certification verdict is 'provisional', not 'certified' — a non-certified record is not " + "leaderboard-comparable (kestrel-m9i.25)"
});
}
let post_cutoff;
if (input.cutoffCheck === undefined || !input.cutoffCheck.ok) {
post_cutoff = "unknown";
reasons.push({
kind: "cutoff-unknown",
detail: "rankable: the model knowledge cutoff is unverifiable (no complete envelope, an unknown model id, or a " + "declared-vs-registry mismatch) — the post-cutoff leg cannot be established, so the row is not rankable " + "(fail-closed, kestrel-m9i.25)"
});
} else if (isPostCutoff(input.cutoffCheck.cutoffMonth, input.sessionDate)) {
post_cutoff = "pass";
} else {
post_cutoff = "fail";
reasons.push({
kind: "pre-cutoff",
detail: `rankable: tape date '${input.sessionDate}' is NOT strictly after the model knowledge cutoff ` + `'${input.cutoffCheck.cutoffMonth}' — the model may have known how the day ended, so a PRE-cutoff row is ` + "not rankable (kestrel-m9i.25)"
});
}
const date_blind = attestationLeg(input.dateBlind);
if (date_blind === "fail") {
reasons.push({
kind: "not-date-blind",
detail: "rankable: the run is attested NOT date-blind (meta.date_blind=false) — the agent could read the calendar " + "date off the tape, so the row is not rankable (kestrel-m9i.25)"
});
} else if (date_blind === "unknown") {
reasons.push({
kind: "date-blind-unknown",
detail: "rankable: the date-blind attestation (meta.date_blind) is absent or malformed — UNKNOWN, so the row is " + "not rankable (fail-closed, kestrel-m9i.25)"
});
}
const season_frozen = attestationLeg(input.seasonFrozen);
if (season_frozen === "fail") {
reasons.push({
kind: "season-not-frozen",
detail: "rankable: the benchmark season is attested NOT frozen (meta.season_frozen=false) — the scenario set is " + "not sealed (ADR-0018), so the row is not rankable (kestrel-m9i.25)"
});
} else if (season_frozen === "unknown") {
reasons.push({
kind: "season-unknown",
detail: "rankable: the season-frozen attestation (meta.season_frozen) is absent or malformed — UNKNOWN, so the " + "row is not rankable (fail-closed, kestrel-m9i.25)"
});
}
const clock_honest = attestationLeg(input.clockHonest);
if (clock_honest === "fail") {
reasons.push({
kind: "not-clock-honest",
detail: "rankable: the clock-honest attestation is REVOKED (meta.clock_honest=false, a platform-side revocation " + "value the driver never stamps) — the session's latency accounting is marked defective, so the row is " + "not rankable (ADR-0040, kestrel-w7la.3)"
});
} else if (clock_honest === "unknown") {
reasons.push({
kind: "clock-honest-unknown",
detail: "rankable: the clock-honest attestation (meta.clock_honest) is absent or malformed — the session is " + "latency-blind or unattested, so the row is not rankable and can never ground a latency claim " + "(fail-closed, ADR-0040, kestrel-w7la.3)"
});
}
const rankable = certified === "pass" && post_cutoff === "pass" && date_blind === "pass" && season_frozen === "pass" && clock_honest === "pass";
return {
legs: { certified, post_cutoff, date_blind, season_frozen, clock_honest },
rankable,
...reasons.length > 0 ? { reasons } : {}
};
}
// src/canonical/json.ts
function canonicalize(value) {
if (value === null)
return null;
if (Array.isArray(value))
return value.map(canonicalize);
if (typeof value === "object") {
const src = value;
const out = {};
for (const key of Object.keys(src).sort()) {
const v = src[key];
if (v === undefined)
continue;
out[key] = canonicalize(v);
}
return out;
}
return value;
}
function canonicalizeJson(value) {
return JSON.stringify(canonicalize(value));
}
function jsonHash(value) {
return sha256(canonicalizeJson(value));
}
// src/blotter/serialize.ts
function serialize(blotter) {
return canonicalizeJson(blotter) + `
`;
}
export { sampledQualified, selectHeadline, nakedShortTaint, readSampledQualificationClaim, canonicalize, canonicalizeJson, jsonHash, project, serialize };