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.
72 lines (71 loc) • 5.95 kB
JavaScript
/**
* # frame/renderer-revision — the ONE-place renderer epoch the stamped `rendering_identity` derives from
* (kestrel-m9i.24)
*
* `rendering_identity` is a comparison axis of the a57.14 envelope + the ConfigId (5zl.6): two runs whose
* authors perceived the machine Frame under DIFFERENT renderers ({@link ./render.ts renderBriefing} /
* `renderWakeDelta`) are DIFFERENT experimental subjects and MUST land in different grid columns (ADR-0013(d):
* a renderer change MINTS a new column, never contaminates an old one). Before m9i.24 the axis was a
* HAND-MAINTAINED FREE LABEL a caller passed (`"unicode-md-v1"`, …), so a renderer BEHAVIORAL change left the
* label unchanged — the kestrel commit is ATT-only — and two runs under different renderers collapsed to the
* SAME ConfigId/CellKey ⇒ no new column ⇒ silent DRIFT.
*
* The fix binds the axis to THIS constant: {@link import("../session/config.ts").deriveRenderingIdentity}
* maps {@link RENDERER_REVISION} to the stamped `rendering_identity`, so a run's identity is DERIVED from the
* renderer's revision, never a string a human bumps out of band.
*
* ## The ONE place (a renderer BEHAVIORAL change MUST bump this)
* {@link RENDERER_REVISION} is an EXPLICIT integer epoch (`kestrel-renderer/<N>`), mirroring the codebase's
* {@link import("../catalog/session-catalog.ts").ENGINE_VERSION} / `JUDGE_VERSION` idiom. It is DELIBERATELY
* DECOUPLED from `PROTOCOL_VERSION` (a wire `major.minor`) and from the kestrel commit (ATT-only): a renderer
* behavior change (a change to {@link ./render.ts} that alters the bytes the author perceives) is neither a
* wire-protocol bump nor a source commit the identity can read, so it MUST be an EXPLICIT epoch bump HERE —
* deriving from either would re-introduce the exact drift m9i.24 closes. Bump this on any renderer-behavior
* change; a bump ⇒ a new derived handle ⇒ a new ConfigId/CellKey (a fresh grid column). No wall clock, no RNG.
*
* ## The bump is no longer honor-system: the epoch is DERIVED-CHECKED (ADR-0052 §5)
* Before, "bump this on any renderer-behavior change" was PROSE — nothing reded when an edit changed the
* bytes an author perceives yet left this constant stale. {@link RENDERER_EPOCH_HASH} closes that: it is a
* sha256 over a PINNED render corpus (every shipped adapter — canonical text + both token-optimal ARMs —
* over a fixed fixture set; see `scripts/percept-lab/render-corpus.ts`), and `scripts/check-renderer-epoch.ts`
* (wired into `bun run check` + CI) RECOMPUTES that hash and REDS when it diverges from this constant. So a
* byte-changing render edit can no longer ship silently: the check fails until the author updates the hash
* AND bumps {@link RENDERER_REVISION} — the epoch cannot lag the bytes.
*
* NOTE — off-limits to the frame barrel: this is a runtime binding, and the `frame` charter barrel
* ({@link ./index.ts}) carries NO runtime exports (Phase-1 invariant), so `config.ts` imports this module
* DIRECTLY, never through the barrel.
*/
/**
* The FROZEN renderer epoch the stamped {@link import("../session/config.ts").deriveRenderingIdentity
* rendering_identity} derives from — an explicit integer epoch (`kestrel-renderer/<N>`). The current renderer
* ({@link ./render.ts}) is revision `8`: revision `1` was the pre-m9i.32 renderer, `2` added the per-frame
* `sizing:` cue (m9i.32), `3` added the arm-time gate-block reason on a plan-state line (`authored
* (blocked: <reason>)`, kestrel-50w), `4` surfaced the position's running unrealized P&L in DOLLARS
* (`unreal=-$25.97`) on the POSITIONS lines (kestrel-c11), `5` NETS same-(instrument, strike, right)
* option legs into ONE positions line (kestrel-dd8) AND populates the option-chain `fair` column from
* ExecutionFair (kestrel-121), and `6` renders an EQUITY/SPOT leg (ADR-0017: no strike/right) as a clean
* `<instrument> shares` on positions/resting/fills — dropping the phantom `<right>@<strike>` chrome and
* the option-only `fair` column that a live model misread as a real (broken) option leg (kestrel-orx),
* `7` surfaced the engine action's `reason` after its id@seq on the L0/L1 ENGINE LOG lines (kestrel-75n),
* and `8` is the wa0j.47 channel-defect pass (ADR-0041 §1): absent position structure/claim render the
* codebook `UNKNOWN` (never a bare `?`), the acting pane's premium-dollars line is labelled `premium
* budget:` (never the bare `budget` that collided with the kernel's R-unit BUDGET section), and `macro`
* left the default OPEN pane set (its v1 absence renders ONCE, on the kernel unavailable line).
* Each changes author-perceived bytes, so per the m9i.24 charter they MUST mint a new column. Bump on any
* renderer-BEHAVIORAL change (see the module header): a bump mints a new derived rendering identity ⇒ a
* new ConfigId/CellKey (a fresh grid column, ADR-0013(d)).
*/
export const RENDERER_REVISION = "kestrel-renderer/8";
/**
* The DERIVED renderer epoch: a sha256 (hex) over the PINNED render corpus — every shipped Rendering
* adapter (canonical text + both `TOKEN_OPTIMAL_ARMS`) rendered over a fixed, date-blind fixture set
* (`scripts/percept-lab/render-corpus.ts renderCorpusText`). This is the byte-level companion to the
* human-facing {@link RENDERER_REVISION} epoch: `scripts/check-renderer-epoch.ts` recomputes the hash
* and REDS (in `bun run check` + CI) whenever it diverges, so a byte-changing edit to ANY adapter
* cannot ship without this constant — and, by the check's instruction, {@link RENDERER_REVISION} —
* moving. Regenerate DELIBERATELY after an intended renderer-behavior change:
* `bun scripts/check-renderer-epoch.ts --write` prints the new hash to paste here. Deterministic
* (the corpus fixtures carry no wall clock / RNG), so the hash is byte-stable across runs.
*/
export const RENDERER_EPOCH_HASH = "e895513070d34ae90cd77654824e86eda0cb83b7d4f0a7620f168075292f7a32";