kestrel.markets/src/react/arms.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.

/**
 * # react/arms — the render-arm registry, mirrored for the browser (ADR-0052 §4)
 *
 * {@link TerminalView} hosts a PRE-RENDERED text Rendering (canonical or a token-optimal ARM) chosen
 * by the host; a host that offers a model-selector needs the available arm identifiers at runtime.
 * The engine's registry ({@link ../frame/render-arm.ts TOKEN_OPTIMAL_ARMS}) is the source of truth,
 * but importing its VALUE would drag the whole renderer graph (tokenizer + sha256) into the browser
 * bundle — a violation of the `/react` isolation requirement (ADR-0052 §3). So the ids are declared
 * HERE and pinned to the engine's {@link RenderArm} union at typecheck:
 *
 *   - `satisfies readonly RenderArm[]` reds if an id is renamed/removed upstream;
 *   - the {@link _AllArmsCovered} exhaustiveness assertion reds if a NEW arm is added upstream and not
 *     mirrored here.
 *
 * Both are TYPE-ONLY couplings (the `import type` is erased) — the registry drifts into a red
 * `bun run typecheck`, never into a shipped browser bundle that disagrees with the engine.
 */

import type { RenderArm } from "../frame/render-arm.ts";

/** Every render-arm id a {@link TerminalView} can be labelled with — `canonical` (the frozen
 * leaderboard control) plus the token-optimal arms. Mirrors the engine's `RenderArm` union. */
export const ARM_IDS = ["canonical", "token-optimal-gemini", "token-optimal-fable"] as const satisfies readonly RenderArm[];

/** The token-optimal arms (the `canonical` control excluded) — the engine's `TOKEN_OPTIMAL_ARMS`. */
export const TOKEN_OPTIMAL_ARM_IDS = ["token-optimal-gemini", "token-optimal-fable"] as const satisfies readonly RenderArm[];

/** A render-arm id — the engine's {@link RenderArm}, re-exported for the `/react` surface. */
export type ArmId = RenderArm;

// ── Drift guards (typecheck-only) ────────────────────────────────────────────
// If a new arm joins `RenderArm` upstream and is not mirrored in ARM_IDS, `_AllArmsCovered` becomes
// `never`, and assigning `true` to a `never`-typed constant reds `bun run typecheck`.
type _AllArmsCovered = Exclude<RenderArm, (typeof ARM_IDS)[number]> extends never ? true : never;
const _assertAllArmsCovered: _AllArmsCovered = true;
void _assertAllArmsCovered;