kestrel.markets/src/session/controller-types.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.

/**
 * # session/controller-types — the LIGHT, pure-TYPE surface of the djm.4 incremental controller.
 *
 * These are the transport-neutral protocol shapes the incremental Session controller answers in — the
 * {@link Delivery} it hands out, the {@link AuthoredResponse}/{@link BoundResponse} a caller replies with,
 * and the {@link SessionResponse}/{@link SessionTranscript} it returns. They were extracted VERBATIM out of
 * {@link ./controller.ts} (which re-exports them, so every existing `from "./controller.ts"` importer is
 * unchanged) into this leaf module for ONE reason: this file's transitive graph is BUILT-IN-FREE (only the
 * light protocol shapes + the frame/agent input contracts), whereas `controller.ts` VALUE-imports the heavy
 * engine (bus / sim / simulate). The djm.5 SDK's LIGHT modules (`src/sdk/types.ts`, `src/sdk/remote.ts`)
 * type-import these shapes from HERE, so the light `./sdk/remote` build entry stays on the `types:[]`
 * zero-built-ins closure — the light/heavy build guard (tsconfig.build.json + tests/package.boundary.test.ts).
 *
 * TYPE-ONLY: every import here is `import type` (erased), so this module adds no runtime weight.
 */

import type { BriefingInput } from "../frame/index.ts";
import type { ActingFrame } from "./agent.ts";
import type { SessionDiagnostic, SessionId, TurnBody, TurnEntry } from "../protocol/session.ts";

/** A Frame delivered to the caller: the date-blind OPEN briefing, or a Wake-delta acting Frame. */
export type SessionFrame = BriefingInput | ActingFrame;

/**
 * A Frame delivery (`session/frame`) awaiting the caller's answer. Binds FOUR pentad legs — Session id,
 * turn ordinal ({@link import("../protocol/session.ts").OPEN_ORDINAL} at OPEN, `0,1,…` per Wake), the prior
 * cursor (`parentHash`), and the content-addressed delivered-Frame root (`frameRoot = sha256(canonical
 * Frame)`). The fifth leg — the exact authored bytes — rides the TURN the caller authors in reply, not the
 * delivery.
 */
export interface Delivery {
  readonly sessionId: SessionId;
  readonly ordinal: number;
  readonly parentHash: string;
  readonly frameRoot: string;
  readonly frame: SessionFrame;
}

/**
 * What the caller authors at a delivered slot — a Kestrel `document`, a legitimate `pass` (standing Plans
 * keep managing), or an explicit `stand-down` (a gradable judgment). The ergonomic L2 input;
 * {@link SessionController.submit} is the explicit-binding L1 input.
 */
export type AuthoredResponse =
  | { readonly kind: "authored"; readonly document: string }
  | { readonly kind: "pass" }
  | { readonly kind: "stand-down"; readonly reason: string };

/**
 * The explicit-binding turn (`session/turn`): the caller supplies the full pentad header + a
 * {@link TurnBody}. This is the idempotency / fail-closed surface — {@link SessionController.submit} builds
 * the incoming {@link TurnEntry} and runs `reconcileTurn` against the entry already recorded at the slot
 * (idempotent duplicate vs. typed conflict).
 */
export interface BoundResponse {
  readonly sessionId: SessionId;
  readonly ordinal: number;
  readonly parentHash: string;
  readonly frameRoot: string;
  readonly body: TurnBody;
}

/** What a committed turn DID to the standing document — the receipt's semantic label, distinct from the
 * {@link TurnBody} vocabulary. `armed`/`revised` supersede; `pass` continues; `stood-down` de-arms;
 * `failure` records a host fault (never confused with a judged stand-down). */
export type TurnDisposition = "armed" | "revised" | "pass" | "stood-down" | "failure";

/** A committed turn's receipt: its content-addressed {@link TurnEntry} (the full pentad) + its disposition. */
export interface TurnReceipt {
  readonly entry: TurnEntry;
  readonly disposition: TurnDisposition;
}

/**
 * The result of answering a slot: an admitted commit carrying the {@link TurnReceipt} and the NEXT eligible
 * {@link Delivery} (`null` at settle), or a fail-closed refusal with a typed {@link SessionDiagnostic} (the
 * committed state is left untouched).
 */
export type SessionResponse =
  | { readonly ok: true; readonly receipt: TurnReceipt; readonly next: Delivery | null }
  | { readonly ok: false; readonly diagnostic: SessionDiagnostic };

/** The re-derived committed transcript (`session/events` resume): the Session id + the pentad-chained
 * {@link TurnEntry} list. `resume` re-derives it — there is nothing to restore. */
export interface SessionTranscript {
  readonly sessionId: SessionId;
  readonly entries: readonly TurnEntry[];
}