UNPKG

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
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 };