kestrel.markets/dist/frame/render.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.

/**
 * # frame/render — the pure Frame renderer (ADR-0008/0009, DATE-BLIND) + the cockpit lead block
 *
 * Two entry points the stepped day runner calls: {@link renderBriefing} materializes the OPEN
 * **keyframe** (full briefing), {@link renderWakeDelta} materializes a WAKE **delta frame**
 * (only what changed since the author's last vantage). Both return a single string, and both
 * **LEAD** with the non-configurable SAFETY / CONTROL **cockpit kernel** (built in code and
 * prepended OUTSIDE any pane/View selection — see {@link renderKernel}).
 *
 * ## The invariants this renderer lives inside (ADR-0009 — not up for grading)
 * - **Invents no value.** Every number printed is a field on the input; an absent/UNKNOWN
 *   field renders as an explicit `—`/`none`/`UNKNOWN` (never a guess). Layout (column position,
 *   axis bounds derived from the data's own extremes, column widths) is computed, but no *value* is.
 * - **The cockpit kernel LEADS every frame and is non-configurable.** It is built in code and
 *   prepended before any pane/View is selected; it can be neither dropped nor reordered by
 *   configuration, and a reserved pane id (`kernel`/`cockpit`) is rejected fail-closed
 *   ({@link ./types.ts RESERVED_PANE_IDS}, {@link ./types.ts assertPaneIdAllowed}). A fail-closed
 *   lead guard ({@link assertKernelLeads}) throws if the kernel is ever not the first block.
 * - **Absent-not-hidden.** Every one of the kernel's 8 fixed-order sections is ALWAYS present —
 *   an empty section renders as an explicit `none`/`UNKNOWN`, never silently dropped.
 * - **Date-blind.** No date/day/epoch token is ever emitted — only relative time and the HH:MM
 *   ET clock the input carries. The wake deadline is a RELATIVE `T-Nm to close` duration, never
 *   a wall-clock/date.
 * - **Deterministic / pure.** No wall clock, no RNG on the render path: the same inputs render a
 *   byte-identical string.
 *
 * ## Parameterized by a Rendering (CONTEXT: Rendering)
 * A Rendering has two parameters — a **format** and the **tokenizer** its token costs are measured
 * under. The SHIPPED format surface is the text screen and only the text screen: {@link RenderFormat}
 * is `ascii | unicode | md`. {@link RenderOptions} threads both parameters through, defaulting the
 * format to `ascii` and the tokenizer to a documented chars/4 estimate.
 *
 * The structural `json` Rendering IS materialized (ADR-0052 §2) — but as its OWN adapter
 * ({@link ./render-json.ts}), NOT as a text screen: this text renderer refuses `json` via
 * {@link assertTextFormat} (routing it here would silently downgrade a structural ask to text). The
 * remaining structural name (`html`) stays the render-core charter's (`src/render`) — speakable
 * ({@link RequestedFormat}) but refused at the boundary ({@link assertFormatMaterialized}) rather than
 * faked. That refusal is the whole contract: callers MUST NOT answer an unmaterialized ask themselves —
 * the prompt harness once "answered" it by silently rendering `ascii` while the run's ConfigId still
 * recorded `json` (kestrel-4gl.26).
 *
 * ## The tape row (rendering-variants.md candidate 2 — the incumbent, first real impl)
 * A candlestick rotated 90°: price runs horizontally, time flows down, each row is a sideways
 * candle — `─` wick spanning the bucket's low→high, `█` body spanning open→close — and the
 * candle's **column position encodes its price level**. The axis header stamps the level range
 * and the anchor clock once (levels are not re-spent per row); a fresh frame re-stamps a fresh
 * anchor (rescale = new anchor line). This is a graded hypothesis, never blessed by taste
 * (ADR-0009); it is the incumbent only because iteration kept this orientation.
 */
import type { BriefingInput, Kernel, WakeDeltaInput } from "./types.ts";
import { type ViewSelection } from "./pane-catalog.ts";
import type { SeatId } from "./seat.ts";
import { DEFAULT_TOKENIZER } from "../render/index.ts";
import type { Tokenizer } from "../render/index.ts";
/** A Rendering's **text-screen format** (CONTEXT: Rendering) — the token-efficient text screen surface
 * THIS renderer produces. `md` is still text.
 *
 * The union names ONLY the TEXT screens this renderer materializes (kestrel-4gl.26): a type that admits
 * a format this renderer cannot produce is an invitation to a silent downgrade, and the harness once
 * took it. The structural `json` Rendering IS materialized ({@link MaterializedFormat},
 * {@link ./render-json.ts}) but is deliberately NOT in this union — it is not a text screen, and the
 * text path refuses it ({@link assertTextFormat}); it is served through the json adapter. `html`
 * remains the render-core charter (`src/render`), refused at the boundary ({@link assertFormatMaterialized})
 * until it exists, never quietly served as a text screen wearing a structured label. */
export type RenderFormat = "ascii" | "unicode" | "md";
/** A **materialized** Rendering format — one the engine can actually produce from a Frame (ADR-0052
 * §2). The text screen ({@link RenderFormat}: `ascii`/`unicode`/`md`) PLUS the structural `json`
 * Rendering ({@link ./render-json.ts}). This is the servable surface: {@link assertFormatMaterialized}
 * vouches for exactly these and refuses everything else (today: `html`, still charter-only). `json` is
 * NOT a {@link RenderFormat} — it is not a text screen, so the TEXT render path ({@link assertTextFormat})
 * refuses it; it is served through the json adapter, never faked as a text screen wearing a json label. */
export type MaterializedFormat = RenderFormat | "json";
/** A format name as it arrives from OUTSIDE the renderer — an authored config, a CLI flag, a JSON
 * file — i.e. before {@link assertFormatMaterialized} has vouched for it. Wider than
 * {@link MaterializedFormat} on purpose: the still-unmaterialized `html` is *speakable* (a config may
 * carry it, and the CLI documents it), it is simply not *servable* — a request for it fails closed. */
export type RequestedFormat = MaterializedFormat | "html";
/** The render **tokenizer** contract + its chars/4 default now live in ONE canonical home — the
 * render barrel {@link ../render/index.ts} (kestrel-2fab) — so the renderer and the pane-budget
 * guard cannot drift apart. Re-exported here for callers that already reach the renderer surface. */
export { DEFAULT_TOKENIZER };
export type { Tokenizer };
/** The two Rendering parameters, both optional (format defaults to `ascii`, tokenizer to the
 * documented chars/4 estimate). A frame renderer stays a pure function of (Frame, RenderOptions).
 *
 * `format` is a {@link RequestedFormat} — what the caller ASKED for — because this interface is the
 * renderer's outer boundary and a caller may honestly ask for a format that does not exist yet. What
 * comes back out is a {@link RenderFormat}: the ask is checked, not coerced. */
export interface RenderOptions {
    readonly format?: RequestedFormat;
    readonly tokenizer?: Tokenizer;
    /** The active View (kestrel-4gl / View-wiring): SELECTS + ORDERS the non-kernel body panes from
     * the pane catalog, honoring its optional token budget. Absent ⇒ the frame kind's DEFAULT View
     * (byte-identical to the pre-catalog hardcoded pane set). The kernel is never a View pane — it
     * LEADS non-configurably, outside this selection. Unknown pane id / over-budget ⇒ fail-closed. */
    readonly view?: ViewSelection;
    /** The acting pod {@link SeatId} for this frame (ADR-0041 §2 / A1, kestrel-wa0j.26). Threaded into
     * {@link resolveView} so a seat with a founder seed for this frame kind reads its graded founder View
     * when NO `view` was authored (the precedence: authored View > seat founder View > phase default).
     * Absent ⇒ no seat is consulted ⇒ byte-identical to before the role axis existed (no-churn). The
     * config opt-in that decides whether a driver supplies this at all lives in `AgentConfig.seatViews`. */
    readonly seat?: SeatId;
}
/** The measured cockpit-kernel block: its text + lines, plus the real token cost under the (labelled)
 * tokenizer and the format it was materialized in. */
export interface KernelPane {
    readonly text: string;
    readonly lines: readonly string[];
    readonly tokenCost: number;
    readonly tokenizer: string;
    readonly format: RenderFormat;
}
/** The token-efficient TEXT screen formats — the {@link RenderFormat} surface {@link assertTextFormat}
 * vouches for. `json` is materialized but is NOT here: it is a STRUCTURAL Rendering, not a text screen. */
export declare const TEXT_RENDER_FORMATS: readonly RenderFormat[];
/** Every **materialized** (servable) Rendering format (ADR-0052 §2): the text screens PLUS `json`. The
 * runtime twin of {@link MaterializedFormat}, and the ONE list {@link assertFormatMaterialized} checks
 * against — `json` moved here from speakable-but-not-servable when its adapter landed
 * ({@link ./render-json.ts}); `html` is still absent (charter-only) and stays refused. */
export declare const MATERIALIZED_FORMATS: readonly MaterializedFormat[];
/**
 * The fail-closed format boundary: vouch for a format the engine can MATERIALIZE, or REFUSE it.
 *
 * This is the ONLY sanctioned way to turn a {@link RequestedFormat} (or a raw string off a config)
 * into a {@link MaterializedFormat}. Exported (kestrel-4gl.26) precisely so no caller has to invent
 * its own answer for an unmaterialized format — the harness once invented one, and the one it invented
 * was a silent downgrade to `ascii` (the fail-OPEN mirror of this guard). There is one honest answer
 * and it lives here: refuse, naming the format and the surface that does exist. Since ADR-0052 §2 the
 * structural `json` Rendering IS materialized ({@link ./render-json.ts}), so it PASSES; `html` remains
 * charter-only and is still refused. A caller that then wants a TEXT screen must narrow further via
 * {@link assertTextFormat} (json is materialized but is not a text screen).
 */
export declare function assertFormatMaterialized(format: string): asserts format is MaterializedFormat;
/**
 * The fail-closed TEXT-SCREEN boundary: vouch for a text-screen {@link RenderFormat}, or REFUSE it.
 *
 * The text render path ({@link renderKernelPane}, the kernel-delta ops) produces a text screen and ONLY
 * a text screen. `json` is materialized ({@link assertFormatMaterialized}) but is NOT a text screen —
 * routing it here would silently downgrade a structural ask to text (the exact fail-OPEN kestrel-4gl.26
 * closed). So this narrower guard refuses `json` (naming the json adapter) AND `html`, and passes only
 * the text screens. A caller with a materialized `json` ask serves it through {@link ./render-json.ts},
 * never through the text path.
 */
export declare function assertTextFormat(format: string): asserts format is RenderFormat;
/**
 * Render the non-configurable cockpit kernel block as a measured {@link KernelPane} — its text +
 * lines, the real token cost under the (labelled) tokenizer, and the format it materialized in.
 * PURE + deterministic; refuses a dishonest claim (fail-closed). The `format` is fail-closed to the
 * text screen ({@link assertFormatMaterialized}).
 */
export declare function renderKernelPane(kernel: Kernel, frameKind: "OPEN" | "WAKE", opts?: RenderOptions): KernelPane;
/**
 * Render the non-configurable cockpit kernel block to a string (the {@link renderKernelPane} text).
 * This is the block every frame LEADS with: a KERNEL sentinel + the 8 fixed-order sections, each
 * always present. Built in code and prepended OUTSIDE any pane/View selection — a configured pane
 * can neither shadow it nor claim its reserved id ({@link ./types.ts assertPaneIdAllowed}).
 */
export declare function renderKernel(kernel: Kernel, frameKind: "OPEN" | "WAKE", opts?: RenderOptions): string;
/**
 * The fail-closed **lead guard** (the TS analogue of the render-layer kernel-lead contract): the
 * non-configurable kernel MUST be the first block of a frame — its first line is the lead sentinel.
 * A rendered frame that does not lead with the kernel is a defect (a caller reordered/dropped it),
 * so this THROWS rather than let a headless frame render. Cheap, pure, and always run before a
 * frame is returned.
 */
export declare function assertKernelLeads(rendered: string): void;
/**
 * Reconstruct the COMPLETE current WAKE kernel text from the reader's cached prior kernel
 * (`prevKernel`) + a delta block (`deltaText`) — the fail-closed composed-completeness operation.
 *
 * The cached prefix supplies the byte-stable skeleton + every UNCHANGED field value; the delta
 * supplies each MOVED field, keyed by its stable anchor. A delta line is `  <anchor> <value>` (the
 * anchor is space-free, so it splits from its value on the first space; the value may contain
 * spaces). FAIL-CLOSED: a missing delta sentinel, a malformed line, or a delta that references an
 * anchor ABSENT from the cached skeleton (a composition that could not be complete) THROWS a
 * {@link KernelHonestyError} — a delta is never allowed to compose to a partial kernel. PURE.
 */
export declare function composeKernelDelta(prevKernel: Kernel, deltaText: string, opts?: RenderOptions): string;
/**
 * Delta-encode the SAFETY/CONTROL kernel of a WAKE frame against the reader's cached prior kernel
 * (`prevKernel`), returning a {@link KERNEL_DELTA_SENTINEL}-led block carrying ONLY the fields that
 * MOVED — or `null` when the kernel's SKELETON changed (a section/list changed shape), signalling the
 * caller to emit a full keyframe instead. Only used where the reader provably holds the prior full
 * kernel (streaming conversation policies), never under `stateless-redraw`.
 *
 * FAIL-CLOSED composed-completeness: before returning, it COMPOSES the delta against `prevKernel`
 * ({@link composeKernelDelta}) and asserts the result is BYTE-IDENTICAL to the full current kernel
 * ({@link renderKernel} `WAKE`); any mismatch (a moved field dropped, an encoding bug) THROWS a
 * {@link KernelHonestyError}. So a delta that ever escapes provably reconstructs the complete kernel.
 * PURE + deterministic. The honesty guard on claims runs via {@link buildKernelCellLines}.
 */
export declare function renderWakeDeltaKernel(prevKernel: Kernel, curKernel: Kernel, opts?: RenderOptions): string | null;
/**
 * Render the OPEN **keyframe** briefing — a full Frame that LEADS with the non-configurable cockpit
 * kernel (built in code, prepended OUTSIDE the pane selection), then the header (relative time
 * only), the instrument specs, the primary instrument's levels, the orientation tape (rotated
 * candlestick), the near-money chain, the macro pane (absent-with-reason in v1), and the acting
 * plan-lifecycle detail. Date-blind: only relative time + the HH:MM ET clock the input carries.
 * PURE (no wall clock / RNG). The lead guard {@link assertKernelLeads} fails closed if the kernel is
 * ever not the first block.
 */
export declare function renderBriefing(input: BriefingInput, opts?: RenderOptions): string;
/**
 * Render a WAKE **delta frame** — a suffix that LEADS with the non-configurable cockpit kernel,
 * then carries only what changed since the author's last vantage: the wake identity
 * (`wake 3 · 41m since last`), the tape since last (its own anchor), the current levels, the
 * near-money chain, and the acting plan-lifecycle detail (its `fillsSinceLast` are the fills since
 * last). Append-only (ADR-0008) and date-blind (EVALUATION.md). PURE; lead-guarded.
 */
export declare function renderWakeDelta(input: WakeDeltaInput, opts?: RenderOptions): string;
/**
 * Render a WAKE **delta frame** for a CACHE-MONOTONE stream (kestrel-312) — identical to
 * {@link renderWakeDelta} except its SAFETY/CONTROL kernel is DELTA-encoded against the reader's
 * cached prior kernel (`prevKernel`): only the fields that MOVED are emitted, the byte-stable
 * skeleton lives in the cached prefix ({@link renderWakeDeltaKernel}). Used ONLY where the reader
 * provably holds the prior full kernel (the `conversation`/`conversation-cached` policies), NEVER
 * under `stateless-redraw` (which gets the self-complete full-kernel {@link renderWakeDelta}).
 *
 * When the kernel's SKELETON changed (a section/list changed shape) the delta encoder returns `null`
 * and this falls back to a full keyframe kernel — a structural change honestly re-keyframes. The
 * fail-closed composed-completeness guard runs inside {@link renderWakeDeltaKernel}; the delta block
 * LEADS the frame ({@link KERNEL_DELTA_SENTINEL}), lead-guarded like any other frame. PURE.
 */
export declare function renderWakeDeltaStreamed(input: WakeDeltaInput, prevKernel: Kernel, opts?: RenderOptions): string;
//# sourceMappingURL=render.d.ts.map