kestrel.markets/dist/protocol/oversight-wire.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.

/**
 * # protocol/oversight-wire — the SNAKE_CASE wire mirror of the oversight contract (kestrel-telx.5).
 *
 * The oversight stream (contract §4) is served over the SAME platform HTTP/SSE dialect the
 * Operation stream is: **snake_case bodies**, an **opaque STRING cursor**, a **closed `event:`
 * enum**. `src/protocol/oversight.ts` is the camelCase DOMAIN contract both Renderings consume;
 * this leaf is its wire face, decoded to the domain types AT THE BOUNDARY (contract §4.4). It is
 * re-exported by {@link ./wire.ts} — the one import path the CLI transport
 * ({@link ../cli/backend/wire.ts}) already re-exports — so there is exactly ONE definition of the
 * oversight wire shapes and exactly ONE definition of the SSE vocabulary (the enum itself stays in
 * `oversight.ts`; nothing here re-declares it). It lives in its own file only because it is long;
 * every consumer reaches it through `wire.ts`, per the bead.
 *
 * ## FAIL CLOSED — a decoder is a GATE, not a cast
 * Every decoder below reads `unknown` and CHECKS each required field, throwing
 * {@link OversightWireError} naming the exact path. A missing / mistyped field is a loud protocol
 * violation, never `undefined` smuggled into a domain type and never a silent default. Nullable
 * contract fields (`fair`, `plan`, `note`, …) are decoded as EXPLICIT `null` — absent-not-hidden —
 * and a `null` where the contract requires a value still reds.
 *
 * ## ZERO runtime dependencies (OSS-ADR-0046 + tests/protocol.boundary.test.ts)
 * The only imports are intra-protocol. In particular this leaf holds NO CLI error type: it throws
 * its own dependency-free {@link OversightWireError}, which the CLI client
 * ({@link ../cli/backend/oversight-remote.ts}) wraps into a `CliError` with code
 * `OVERSIGHT_PROTOCOL_VIOLATION` (contract §4.3 rule 1/2). Same discipline as
 * {@link ../client/sse-transport.ts}: the transport/decoder layer is error-agnostic, the caller owns
 * the error TAXONOMY.
 *
 * ## NOT in the shipped JSON Schema (slice-1 posture)
 * `scripts/gen-wire-schema.ts` reflects an explicit root list (`WIRE_COMPOSITES`, the ten slice-1
 * RESPONSE composites). The oversight shapes are deliberately NOT added to it: the platform route
 * (§4.1) does not exist yet, and shipping a schema for a route nobody serves would be a gate whose
 * stated coverage exceeds its actual coverage. Adding them is a one-line follow-up when the route
 * lands.
 */
import type { AgentTierStatus, Authorship, BookView, Caller, KernelBrief, KernelBudget, KernelClaim, KernelEngineAction, KernelField, KernelFill, KernelLeg, KernelMandate, KernelOwnerAct, KernelPlanState, KernelPosition, KernelRestingOrder, KernelVehicleHealth, KernelWake, OrgNode, OversightAct, OversightActRecord, OversightDelivery, OversightEscalation, OversightEvent, OversightEventType, OversightFrame, OversightIdentity, OversightKernel, OversightMessage, OversightTurn, PodView, RiskEnvelope, SpectatorFrame, SpectatorPane } from "./oversight.ts";
import type { TurnBody, TurnEntry } from "./session.ts";
/** A wire body that does not match the contract. Dependency-free on purpose: the CLI wraps it as a
 *  `CliError{code:"OVERSIGHT_PROTOCOL_VIOLATION"}`, the SDK could wrap it as its own. */
export declare class OversightWireError extends Error {
    readonly path: string;
    constructor(path: string, detail: string);
}
export declare function decodeCaller(v: unknown, path?: string): Caller;
export declare function decodeOversightIdentity(v: unknown, path?: string): OversightIdentity;
export declare function decodeKernelField(v: unknown, path: string): KernelField;
export declare function decodeKernelLeg(v: unknown, path: string): KernelLeg;
export declare function decodeKernelPosition(v: unknown, path: string): KernelPosition;
export declare function decodeKernelRestingOrder(v: unknown, path: string): KernelRestingOrder;
export declare function decodeKernelFill(v: unknown, path: string): KernelFill;
export declare function decodeKernelPlanState(v: unknown, path: string): KernelPlanState;
export declare function decodeRiskEnvelope(v: unknown, path: string): RiskEnvelope;
export declare function decodeKernelBudget(v: unknown, path: string): KernelBudget;
export declare function decodeKernelWake(v: unknown, path: string): KernelWake;
export declare function decodeKernelVehicleHealth(v: unknown, path: string): KernelVehicleHealth;
export declare function decodeKernelEngineAction(v: unknown, path: string): KernelEngineAction;
export declare function decodeKernelOwnerAct(v: unknown, path: string): KernelOwnerAct;
export declare function decodeKernelClaim(v: unknown, path: string): KernelClaim;
export declare function decodeKernelMandate(v: unknown, path: string): KernelMandate;
export declare function decodeKernelBrief(v: unknown, path: string): KernelBrief;
/** The acting kernel. EVERY section is required on the wire (absent-not-hidden, §3.2): an absent
 *  source section arrives as an explicit `null`/`[]`, never as a dropped key. */
export declare function decodeOversightKernel(v: unknown, path?: string): OversightKernel;
export declare function decodeAuthorship(v: unknown, path: string): Authorship;
export declare function decodeAgentTierStatus(v: unknown, path: string): AgentTierStatus;
export declare function decodeBookView(v: unknown, path: string): BookView;
export declare function decodePodView(v: unknown, path: string): PodView;
export declare function decodeOrgNode(v: unknown, path: string): OrgNode;
export declare function decodeSpectatorPane(v: unknown, path: string): SpectatorPane;
export declare function decodeSpectatorFrame(v: unknown, path: string): SpectatorFrame;
export declare function decodeOversightMessage(v: unknown, path: string): OversightMessage;
export declare function decodeOversightFrame(v: unknown, path?: string): OversightFrame;
export declare function decodeOversightDelivery(v: unknown, path?: string): OversightDelivery;
export declare function decodeTurnBody(v: unknown, path: string): TurnBody;
export declare function decodeTurnEntry(v: unknown, path: string): TurnEntry;
export declare function decodeOversightTurn(v: unknown, path?: string): OversightTurn;
export declare function decodeOversightEscalation(v: unknown, path?: string): OversightEscalation;
export declare function decodeOversightAct(v: unknown, path?: string): OversightAct;
export declare function decodeOversightActRecord(v: unknown, path?: string): OversightActRecord;
/**
 * The oversight SSE frame's JSON `data:` payload — the mirror of {@link ./wire.ts WireOperationEvent}.
 * `cursor` echoes the SSE `id:` line (an OPAQUE STRING — §4.3 rule 6: never parsed), `type` is the
 * closed enum from `oversight.ts` (ONE definition — this shape re-declares nothing), and the
 * type-specific body rides in `data` as snake_case.
 */
export interface WireOversightEvent {
    readonly cursor: string;
    readonly type: OversightEventType;
    readonly session_id: string;
    readonly data?: Record<string, unknown>;
}
/**
 * Decode ONE typed oversight event body into the camelCase domain union (contract §4.2 table).
 *
 * `type` MUST already have been admitted against `isOversightEventType` (§4.3 rule 1 — the
 * transport's closed-vocabulary gate); this decoder is TOTAL over the enum, so a member added to
 * the enum without a case here is a compile error (the `never` exhaustiveness arm), not a silent
 * pass-through.
 */
export declare function decodeOversightEvent(type: OversightEventType, data: unknown): OversightEvent;
/**
 * The BUS-BACKED `seq` of a decoded event, or `null` for the two members that carry none
 * (`oversight.snapshot` — a projection; `oversight.diagnostic` — nothing landed; `oversight.failed`
 * — the stream is dying). This is the input to §4.3 rule 4 (monotone seq): the rule can only apply
 * where the contract says a `seq` exists, so the extraction lives HERE, beside the shapes, rather
 * than being re-derived by each client.
 */
export declare function busSeqOf(e: OversightEvent): number | null;
//# sourceMappingURL=oversight-wire.d.ts.map