kestrel.markets/dist/bus/write.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.

/**
 * # bus/write — the single-writer, append-only JSONL bus writer (RUNTIME §1)
 *
 * `BusWriter` is the ONE thing that assigns `seq`. It is a **single writer** by contract:
 * one writer owns one file; `seq` is monotonic and gap-free from 0; every `append` emits
 * exactly one JSONL line and **flushes it** (each event is durable the instant it is
 * written — that is what makes the reader's torn-final-line tolerance the only crash mode
 * it must handle, RUNTIME §1).
 *
 * The envelope is serialized in canonical field order `{seq, ts, stream, type, ...payload}`
 * (RUNTIME §1). Serialization is a pure function of the event, so the same event sequence
 * always produces byte-identical text — the determinism substrate for replay (RUNTIME §0)
 * and for byte-identical synthetic sessions.
 */
import type { BookPayload, BusEvent, ControlPayload, DetectorPayload, HeartbeatPayload, JournalKind, MetaPayload, NewBusEvent, OrderAction, OrderPayload, PlanPayload, RegimePayload, SpotPayload, WakeKind, WakePayload } from "./types.ts";
/** Serialize one event to its single JSONL line (including the trailing newline).
 * Canonical field order: `seq, ts, stream, type`, then payload in declaration order. */
export declare function serializeEvent(event: BusEvent): string;
/** Serialize a whole event sequence to bus text. Pure and total: same events ⇒ same bytes. */
export declare function serializeBus(events: Iterable<BusEvent>): string;
/** Write a whole (already-`seq`-stamped) event sequence to a file in one shot. Used to
 * persist a synthetic session; `BusWriter` is for incremental engine writes. */
export declare function writeBusFile(path: string, events: Iterable<BusEvent>): Promise<void>;
/**
 * Stamp a `seq` onto a seq-less event, producing the CANONICAL-ORDER envelope
 * `{seq, ts, stream, type, ...payload}` (RUNTIME §1) — **the one owner of bus field order**.
 *
 * It re-canonicalizes rather than prepending, and that is the whole point: `serializeEvent` is
 * `JSON.stringify`, which is INSERTION-ORDER-dependent, so a caller spreading a payload that itself
 * carries `ts`/`stream`/`type` mid-object (`{ stream, type, ...held.thetaBleed }` where `thetaBleed`
 * owns a `ts`) would otherwise serialize a NON-canonical record onto the graded bus. Destructuring the
 * envelope fields out and re-emitting them first makes the canonical order a property of this function
 * instead of a discipline every call site must remember (kestrel-byfl; the pta5 instance).
 *
 * `type` is re-emitted ONLY when the caller has one: JOURNAL's discriminant is `kind`, not `type`
 * ({@link BusWriter.appendJournal}), and an unconditional `type` would inject a `type: undefined` key
 * into the in-memory envelope — invisible in the bytes (`JSON.stringify` drops it) but visible to any
 * reader that asks `"type" in ev`. Never a silent default.
 *
 * The cast is the single boundary where the flat union is reassembled; the overloads on
 * {@link BusWriter.append} and the {@link NewBusEvent} shape guarantee the fields are right.
 */
export declare function canonicalEnvelope(seq: number, ev: NewBusEvent): BusEvent;
/**
 * The single writer of a bus file. Construct one per session; `append` stamps the next
 * `seq`, writes the JSONL line, and flushes. `close()` ends the underlying sink; any
 * `append` after `close()` throws (single-writer, no-reopen).
 *
 * `append(stream, type, payload, ts)` is overloaded per stream so the payload is checked
 * against the stream/type pair. The returned value is the fully-stamped event (with `seq`),
 * so a caller can echo it or fold it immediately.
 */
export declare class BusWriter {
    #private;
    constructor(path: string);
    /** The next `seq` that will be assigned (i.e. the count of events written so far). */
    get nextSeq(): number;
    append(stream: "META", type: "session", payload: MetaPayload, ts: number): BusEvent;
    append(stream: "TICK", type: "SPOT", payload: SpotPayload, ts: number): BusEvent;
    append(stream: "TICK", type: "BOOK", payload: BookPayload, ts: number): BusEvent;
    append(stream: "TICK", type: "HEARTBEAT", payload: HeartbeatPayload, ts: number): BusEvent;
    append(stream: "DETECTOR", type: string, payload: DetectorPayload, ts: number): BusEvent;
    append(stream: "PLAN", type: "lifecycle", payload: PlanPayload, ts: number): BusEvent;
    append(stream: "ORDER", type: OrderAction, payload: OrderPayload, ts: number): BusEvent;
    append(stream: "WAKE", type: WakeKind, payload: WakePayload, ts: number): BusEvent;
    append(stream: "CONTROL", type: string, payload: ControlPayload, ts: number): BusEvent;
    append(stream: "REGIME", type: "tag", payload: RegimePayload, ts: number): BusEvent;
    /**
     * Append a JOURNAL record — the author's reasoning, full markdown `body` inline (bus_schema
     * v2). JOURNAL has no engine `type`; its discriminant is `kind`, so it takes its own writer
     * method rather than an {@link append} overload. Mints the next `seq` exactly like `append`,
     * which is what makes the pre-hoc/post-hoc seq contract a fact of the log: write an `author`
     * record before you arm and its `seq` is provably below the first armed PLAN's; append a
     * `debrief` after CLOSE and its `seq` is provably above the CLOSE's.
     *
     * JOURNAL is author metadata, never an engine input — appending these records cannot move the
     * emitted engine event stream or the determinism hash (the determinism invariant, a57.11).
     */
    appendJournal(kind: JournalKind, body: string, ts: number): BusEvent;
    /** End the sink and forbid further appends. Idempotent. */
    close(): Promise<void>;
}
//# sourceMappingURL=write.d.ts.map