/** * # session/sim — the sim Session driver + graded report (RUNTIME §7) * * The one object that owns a `sim` run, wired end to end over the shipped substrate. It reads a * recorded/synthetic bus **as its clock** (`now` = each event's `ts`, RUNTIME §0), drives the * canonical market state and the {@link PlanEngine} trigger sweep, routes the engine's orders * through the **Gate** into a {@link SimFillEngine} (the judge, RUNTIME §6), reassesses resting * orders on every BOOK event (and resting SPOT orders on every SPOT tick carrying an NBBO, * ADR-0017), feeds the resulting fills **back** into the engine's org facts and onto the emitted * bus, cash-settles held inventory off the final spot — options at intrinsic, spot inventory * mark-to-market (ADR-0017) — and returns a graded {@link EpisodeReport}. * * One code path, one gate (RUNTIME §7): swapping the gate adapter is what turns this into paper * or live; nothing else changes. Every mode crosses the same fill model, so grades compare on * fills, not on fill assumptions (ARCHITECTURE §4). * * ## The per-event pass (no look-ahead — state at event N is a function of events ≤ N) * For each bus event, in order: * 1. **clock** — the gate's `now` is pinned to the event's `ts` (the Gate seam is `now`-less; * the driver owns the injected clock, RUNTIME §0). * 2. **canonical state** — {@link CanonicalState.applyEvent} folds SPOT/HEARTBEAT into the * signal instrument's one causal coordinate (the market-fact substrate the triggers read). * 3. **fill reassessment (BOOK only, BEFORE the sweep)** — the market acts first: every leg of * the book reassesses the matching resting orders through {@link SimFillEngine.onBook}; a * strict-cross floor fill is emitted **and fed back** into the engine (`engine.onEvent(fill)`) * so inventory, basis, and TP maintenance advance — all **before** the engine reacts to that * book. This is the load-bearing ordering (RUNTIME §7): a plan can never cancel/reprice an * order the same book would have filled. * 4. **engine sweep** — {@link PlanEngine.onEvent} arms/fires/manages; its PLAN + WAKE land on * the emitted bus, its order submits/cancels go through the {@link SimGate} into the fill * engine (each `place`/`cancel` ORDER event drained onto the emitted bus at submission time). * Orders placed *by this sweep* rest for the **next** book (fills are reassessed on book * events, one book at a time). * * At session end the fill engines **settle** at the final exec spot: filled option inventory * settles at intrinsic, filled spot inventory marks to the final spot (ADR-0017 — no expiry, no * intrinsic), still-resting orders expire worthless-unfilled ($0 floor). The report carries the * floor outcome and the E[$] under `pFill` side by side (RUNTIME §6). * * ## Determinism (RUNTIME §0/§7 — a test, not a hope) * Everything on the path is pure and injected-time; the emitted stream is stamped with a * monotonic `seq` in emission order and serialized canonically. `determinism_hash` is the * sha256 of that serialization: two runs on the same inputs produce the identical hash, and a * zero-documents run produces a stable pass-through hash. * * ## Fail-closed (RUNTIME §8, all loud) * No META header → refuse (a well-formed bus opens with exactly one META). Unknown fill model → * refuse to grade (never default silently). No instruments → refuse. Bus corruption surfaces * from {@link readBus} as a loud, line-located error. */ import type { BookState, BusEvent, ExperimentalEnvelope, Fidelity, FillModelStamp, InstanceIdentity, MetaEvent, Mode, NewBusEvent, OrderEvent, PlanOutcome, PlanState, Right, SampledQualificationClaim } from "../bus/index.ts"; import { CanonicalState, type SeriesProvider } from "../series/index.ts"; import { PlanEngine, type Gate, type InstrumentSpec, type OrderIntent, type OrderRole } from "../engine/index.ts"; import { type FairTauProvider } from "./clock.ts"; import { requireMeta, resolveSpecs, specFromMeta } from "./specs.ts"; import { SimFillEngine, SpotFillEngine, type EpisodeSigmoidParams, type FillModel, type SettleMark, type SpotSettleReport } from "../fill/index.ts"; import { type KestrelNode, type Module, type PlanStatement } from "../lang/index.ts"; import { type Blotter } from "../blotter/index.ts"; import { type HeadlinePnl } from "../grade/headline.ts"; import type { AgentConfig } from "./agent.ts"; import type { CarriedLot } from "../fill/index.ts"; import type { SessionCarry } from "./carry.ts"; /** The two shipped, named fill models (RUNTIME §6). Any other name is refused (fail-closed). */ export type FillModelName = "strict-cross-v1" | "maker-fair-v1"; /** * The machine-readable reason code a session de-arms under when the exec book's time-to-expiry is * unknowable (kestrel-wcnd) — it prefixes the CONTROL `disarm` note, which the Blotter projects as * a reason-carrying de-arm record (`disarms[].reason`, kestrel-2pl). Exported so a consumer (and * the guard fixture) matches the CODE rather than scraping prose. */ export declare const FAIR_TAU_UNKNOWN_CODE: "fair-tau-unknown"; /** Options for {@link runSimSession}. Exactly one of `busPath`/`events` supplies the bus. * `documents` are already-parsed Kestrel nodes (a bare statement or a full module — both are * normalized to a module and armed). Instrument contract facts are not on the v1 bus META, so * they are derived from the asset class (tick `0.01`, strike step `1`, multiplier `100` for an * option-underlier else `1`, role carried from META) unless `instruments` overrides them. * `fairTauYears` injects time-to-expiry so `@fair` (and the maker-fair hazard) can be built; * **absent, it defaults to the CONTRACT-expiry tau** ({@link expiryTauYears}: `max(0, 16:00 ET on * the book's OWN expiry − now)`, RUNTIME §4) — so `@fair` is buildable by default, decays toward * the contract's expiry (not this session's close, kestrel-wcnd), and goes UNKNOWN (fail-closed, * see {@link SessionCore.step}) when a book names no resolvable expiry. */ export interface RunSimOptions { readonly busPath?: string; readonly events?: readonly BusEvent[]; readonly documents: readonly KestrelNode[]; readonly fillModel: FillModelName; readonly rUsd: number; readonly out?: string; readonly instruments?: readonly InstrumentSpec[]; readonly fairTauYears?: FairTauProvider; /** Calibrated maker-fair fill params (the `episode-sigmoid-u-v1` form). When present with * `fillModel: "maker-fair-v1"`, the session grades under the calibrated curve instead of the * uncalibrated default hazard (RUNTIME §6). Ignored by `strict-cross-v1`. */ readonly makerFairParams?: EpisodeSigmoidParams; /** An optional agent config (kestrel-5zl.6). When supplied AND it declares an authoring identity, its * a57.14 experimental envelope is captured (`envelopeForConfig`) and stamped on the graded META. A * config-less run (the default) stamps no envelope — byte-identical to before (backward-compatible). */ readonly config?: AgentConfig; } /** One transition in a plan's lifecycle trace (RUNTIME §5), reconstructed from the emitted PLAN * stream. */ export interface PlanLifecycleStep { readonly ts: number; readonly state: PlanState; readonly outcome?: PlanOutcome; readonly reason?: string; } /** A plan's lifecycle trace + its terminal state (the outcome when `done`, else the last * lifecycle state). ONE trace is one exact Plan **instance** (kestrel-22j.15): a legal same-name replacement * is its OWN trace beside its predecessor, never collapsed into it. */ export interface PlanTrace { /** The authored plan NAME — the Lineage aggregation key (a name may legally recur; NOT the instance id). */ readonly plan: string; /** The exact Plan-instance identity this trace belongs to (kestrel-22j.15) — the id the engine minted, * carried on the emitted PLAN stream. Distinct per instance, so two same-name instances are two traces. */ readonly plan_instance: string; readonly lifecycle: readonly PlanLifecycleStep[]; readonly final_state: PlanState | PlanOutcome; } /** One gate order, joined across the intent (resolution annotation, role), the engine child * (esc stage), and the fill engine outcome (`pFill`, floor fill, settle P&L). */ export interface OrderReport { readonly ref: string; readonly plan: string; /** The authoring plan's exact INSTANCE identity (kestrel-22j.15) — carried from the order intent so an * order joins its exact instance, not merely its recurring name. */ readonly plan_instance: string; readonly role: OrderRole; readonly instrument: string; readonly side: "buy" | "sell"; readonly qty: number; /** The option strike; ABSENT for a spot/equity order (ADR-0017 — no fictional strike). */ readonly strike?: number; /** The option right; ABSENT for a spot/equity order (ADR-0017). */ readonly right?: Right; readonly px: number; /** The price-resolution annotation (`fair=fallback(mid)`, …) — a silent mid is forbidden, * RUNTIME §4. */ readonly annotation: string; /** The esc stage this resting order occupied (RUNTIME §4/§5) — the ladder rung, NOT a count of * reprices (the honest session-wide reprice tally is `session.reprice_count`, F6). */ readonly esc_stages: number; /** Expected fill probability `1 − survival` (`1` on a floor fill). */ readonly pFill: number; /** Did the strict-cross floor fire? */ readonly filled: boolean; /** The floor fill price, else `null`. */ readonly fillPx: number | null; /** Realized $ under the floor (0 unless floor-filled). */ readonly floorPnl: number; /** E[$] under `pFill`. */ readonly expectedPnl: number; /** Present + `true` when the order was cancelled mid-session (esc-replaced, TTL/INVALIDATE * pulled, or CANCEL-IF) rather than filled or settled. */ readonly cancelled?: boolean; } /** The graded sim report (RUNTIME §7). Stamps its judge (`fill_model`) and carries the * determinism hash of the emitted event stream. */ export interface EpisodeReport { readonly session: { readonly date: string; readonly instruments: readonly string[]; readonly mode: "sim"; readonly fill_model: string; readonly bus_events: number; /** sha256 of the emitted PLAN/WAKE/ORDER stream — pins the engine's OUTPUT (RUNTIME §0/§7). */ readonly determinism_hash: string; /** sha256 of the raw INPUT bus (serialized events) — pins what the run was graded against, so * determinism_hash (output) and bus_sha256 (input) together bind the whole computation (F6). */ readonly bus_sha256: string; /** Count of actual cancel/replace reprice submissions across the session (peg + esc), from the * engine — the honest reprice tally (F6; `orders[].esc_stages` is the ladder rung, not a count). */ readonly reprice_count: number; /** The **last bus event `ts`** — the session clock's final value (settle time). Injected, never * wall-clock (RUNTIME §0); the natural deterministic `now` for recording this run into the * ledger (ADR-0006). Equals `firstTs` for an empty bus. */ readonly settle_ts: number; }; readonly plans: readonly PlanTrace[]; readonly orders: readonly OrderReport[]; /** The three-channel P&L contract (kestrel-9gu.12): floor + expected always, sampled on a seeded run, * and the HEADLINE selected by the fail-closed qualification gate (floor until 9gu.8.6 passes). */ readonly totals: { /** Realized $ under the deterministic strict-cross floor — the honest lower bound. */ readonly realized_floor_usd: number; /** E[$] under the survival product — the analytic bound beside the realization. */ readonly expected_usd: number; /** The seeded causal realization (one ensemble replicate, ADR-0016). Present ONLY on a `fillSeed` * run — an un-run channel is never conflated with a zero outcome (kestrel-9gu.12). */ readonly sampled_usd?: number; readonly premium_spent: number; /** The settle mark's provenance + fail-closed staleness verdict + annotated recovery * (kestrel-xwf): the spot the book cash-settled against (`px` — the parity-recovered value when * `source: "parity"`), WHEN the primary mark's value was last established on the input tape * (`as_of_ts`; a frozen feed re-printing the same px does not refresh it), its age vs the settle * instant, and the `stale` verdict under the declared threshold. `stale: true` means the totals * above are graded against a mark the tape stopped supporting — NON-BANKABLE (a parity recovery * annotates, it does not pardon), never a silently fresh-looking number (the taint also rides the * Blotter's `totals.headline`). `source`/`mark_uncertain`/`note` are the recovery annotation: * `"parity"` = recovered honestly from a two-sided closing book; `"stale"` = refused — * `mark_uncertain: true`, the last mark retained. Explicit `null`s (never omitted keys) so the * report's shape is fixed. */ readonly settle_mark: { readonly px: number; readonly as_of_ts: number | null; readonly last_observed_ts: number | null; readonly age_ms: number | null; readonly stale_after_ms: number; readonly stale: boolean; readonly source: "market" | "parity" | "stale"; readonly mark_uncertain: boolean; readonly note: string | null; }; /** WHICH channel is the headline + the gate verdict that selected it + the xwf settle taint * ({@link HeadlinePnl}, kestrel-9gu.12). `floor` today; `sampled` once the 9gu.8.6 qualification is * on the record (never with extrapolated-support sampled realizations — bankableEv stays). The * settle-mark staleness verdict above feeds this headline's taint (a stale mark — including a * parity-recovered one — taints whichever channel leads). */ readonly headline: HeadlinePnl; }; readonly emitted: Readonly>; } /** * @deprecated Renamed to {@link EpisodeReport} (kestrel-markets-jcn0): the * deterministic execution unit is an **Episode**, not a "Kestrel Session" * ("session" is now reserved for the stateful TerminalSession seat, * PLAT-ADR-0052). This alias keeps `engine.session.SessionReport` type-importers * compiling across the rename; it will be removed after the 0.8.0 public cutover. * The on-the-wire report shape (its `session` payload field, `sessionId` keys) is * unchanged — this is a type-name-only rename, wire contract untouched. */ export type SessionReport = EpisodeReport; /** The canonical parse-print text of an armed document set — the byte-stable printer projection * (ADR-0001), documents joined by a blank line (matching the CLI's canonical plans text / the ledger's * `plans_sha256` input). Its sha256 is {@link InstanceIdentity.version}. A `Module` is a `KestrelNode`, * so this is the {@link canonicalPlansText} owner (canonical/plans) applied to an armed module set. */ export declare function canonicalPlansTextOf(modules: readonly Module[]): string; /** The fill-model judge stamp for a GRADED bus's META. `name`/`version` are the model's identity; * `calibration_sha` is a stable digest of the calibration descriptor; `self_limitation` is what the judge * DECLARES it could not observe (a57.4) — stamped verbatim so the projector never re-guesses it from `name` * (the mislabel of the calibrated judge, kestrel-o32) ({@link FillModelStamp}). */ export declare function fillModelStampOf(model: FillModel): FillModelStamp; /** The Instance identity for a GRADED bus's META (ADR-0011 recommendation 1, ADR-0006 names-are-data): * `lineage` = the authored NAME (the Pod's when the document set runs a Pod, else the first authored * plan/book statement's), `version` = `plans_sha256`, `mode` = the session mode, `pod` present ONLY for * an actual Pod document. A zero-document grade authors nothing ⇒ an empty `lineage`. */ export declare function instanceIdentityOf(modules: readonly Module[], mode: Mode): InstanceIdentity; /** Fidelity level for a mode (CONTEXT: Fidelity): sim/paper are `modeled`, live is `realized`. */ export declare function fidelityOf(mode: Mode): Fidelity; /** Stamp a GRADED bus's opening META: the input session header + the judge self-description * (`fill_model` + `instance` + `fidelity`) and, when supplied, the author's a57.14 experimental * `envelope` (the config's captured identity — kestrel-5zl.6) plus the FULL `config_id` * (`sha256(canonical AgentConfig)` — the sampling-axis-complete identity the grid CellKey keys on, * m9i.2 owner tweak). Advertises the current {@link BUS_SCHEMA} (v6 — a graded bus is the ONLY stamping * site that follows the bump; input tapes keep their pinned literal, clock-honest wakes §1) and, for a * verified clock-honest session, the `clock_honest: true` attestation (ADR-0040 — `true` or ABSENT, * never `false`). Keeps the input META's `seq`/`ts`. Pure. Only a GRADED bus carries these; an INPUT * tape's META stays judge-less (the two-bus rule, ADR-0011). The `envelope`/`config_id` keys are OMITTED * entirely when absent — a config-less graded bus is byte-identical to before (backward-compatible; * a57.14 leaves it `certified`). */ export declare function stampGradedMeta(inputMeta: MetaEvent, judge: { fillModel: FillModelStamp; instance: InstanceIdentity; fidelity: Fidelity; envelope?: ExperimentalEnvelope; configId?: string; cellConfigId?: string; sampledQualification?: SampledQualificationClaim; /** The clock-honest attestation (ADR-0040 / kestrel-w7la.1): pass `true` ONLY when the session ran * clocked semantics AND the data-floor verification held. The stamp is `true` or ABSENT — never * `false` (`false` is reserved platform-side as a revocation value; clock-honest wakes §5). */ clockHonest?: true; }): MetaEvent; /** Assemble the canonical GRADED bus for a session: the judge-stamped opening META (seq 0) followed by * the engine's emitted reactions (PLAN/WAKE/ORDER/TELEMETRY, incl. the settle-outcome records), * re-stamped `seq` 1..N so the stream is gap-free from 0 and opens with exactly one META — a well-formed * bus {@link readBus} accepts. This is the self-describing artifact the Blotter projector (slice 2) will * consume; slice 1 uses it to PROVE totals{floor,expected} + orders[].support re-derive from bus bytes * with no engine-state scrape. Pure. */ export declare function assembleGradedBus(gradedMeta: MetaEvent, emitted: readonly BusEvent[]): BusEvent[]; /** The append-only emitted stream: stamps a monotonic `seq` in emission order and serializes * canonically (the determinism substrate, RUNTIME §0/§1). */ declare class EmittedStream { #private; readonly events: BusEvent[]; /** Stamp the next `seq` and land the event in CANONICAL field order. The canonicalization is * {@link canonicalEnvelope} — the SAME owner {@link import("../bus/write.ts").BusWriter} stamps * through, never a second copy of the order — because a bare `{ seq: this.#seq++, ...ev }` would * preserve the CALLER's key order verbatim: an emitter spreading a payload that carries * `ts`/`stream`/`type` mid-object then serializes a non-canonical record onto the graded bus * (`serializeEvent` is `JSON.stringify`, insertion-order-dependent). That was kestrel-pta5 — * `theta_bleed` put `ts` after `type` — patched at the one call site with the class left open; * kestrel-byfl closes the class here, so no present or future emitter can reintroduce it. */ emit(ev: NewBusEvent): BusEvent; hash(): string; } /** The sim Gate: rests engine order intents in the {@link SimFillEngine} — or, for a SPOT/equity * intent (no strike/right, ADR-0017 / kestrel-20f.14), in the instrument-keyed * {@link SpotFillEngine} — and cancels them, pinning the injected clock (`now`) the driver sets * each event. Every `place`/`cancel` drains the fill engines' fresh ORDER events onto the * emitted bus at submission time. */ export declare class SimGate implements Gate { private readonly fill; private readonly spotFill; /** Whether spot orders may grade in this session — only the strict-cross family has a spot * judge today; a spot order under `maker-fair-v1` is REFUSED loudly (no spot hazard model * exists — never grade under a judge that cannot assess the instrument, RUNTIME §8). */ private readonly spotAllowed; private readonly drain; now: number; readonly intents: OrderIntent[]; constructor(fill: SimFillEngine, spotFill: SpotFillEngine, /** Whether spot orders may grade in this session — only the strict-cross family has a spot * judge today; a spot order under `maker-fair-v1` is REFUSED loudly (no spot hazard model * exists — never grade under a judge that cannot assess the instrument, RUNTIME §8). */ spotAllowed: boolean, drain: () => void); submit(intent: OrderIntent): string; cancel(ref: string): boolean; } /** * Derive a closing settle spot from **put-call parity** on a two-sided book: at (near-)expiry the * forward ≈ spot, so `C − P = S − K ⇒ S = K + (C_mid − P_mid)` for the strike nearest `nearSpot` that * quotes BOTH a two-sided call and a two-sided put. Returns the parity spot + the strike used, or * `null` when no strike has both sides two-sided (parity not derivable → fail-closed to a taint). * * Mids are used ONLY as a settle-mark of last resort when the primary feed died — never as an * execution anchor (the never-a-mid-anchor rule governs FILL prices, RUNTIME §4) — and the result is * always flagged as recovered-from-stale, never silently banked as a live mark. * * The caller supplies the CLOSING legs: {@link SessionCore} feeds this only quotes whose values are * FRESH at the settle instant (carried on a BOOK event within the declared settle-mark staleness * threshold, {@link SETTLE_MARK_STALE_AFTER_MS}) — a two-sided pair surviving in the FOLDED book * from hours before the option feed died is NOT a closing strike, and "recovering" from its stale * mids would launder one dead feed through another (the DEGRADED-DATA cell's dark-to-close shape). */ export declare function closingParitySpot(book: Pick | undefined, nearSpot: number): { spot: number; strike: number; } | null; /** The wired core internals a {@link SessionCoreOptions.liveGate} factory is handed to build its Gate. * It reads canonical state / the folded books the core already owns (never a second copy) and appends * the venue's own ORDER events onto the session's single live bus. */ export interface LiveGateWiring { readonly state: CanonicalState; readonly execSpec: InstrumentSpec; readonly signalSpec: InstrumentSpec; /** The core's folded option books (per instrument) — the same map a Frame renders, read by a paper * gate's price-anchor wall so the driver keeps no second book of its own. */ readonly books: ReadonlyMap; /** Append ONE venue-emitted ORDER event onto the session's single live bus (stamps `seq`, stripping * any venue-local one), returning the stamped event. A `fill` is additionally queued to be fed back * into the engine AFTER the sweep (the broker fills-after-sweep ordering — the venue acts, the engine * reacts next). */ appendVenueEvent(ev: BusEvent | NewBusEvent): BusEvent; } /** What a {@link SessionCoreOptions.liveGate} factory returns — the injected Gate plus the two thin * hooks the live progression needs the core's per-event pass to call. Every field but `gate` is * optional; the sim path uses none of this. */ export interface LiveGateBinding { /** The gate orders route through (the L0-clamped paper/live gate) — REPLACES the reference SimGate. * Its `now` is pinned by the core each event exactly as `SimGate.now` is (RUNTIME §0). */ readonly gate: Gate & { now: number; }; /** Wrap the core's canonical series provider before the engine reads it — the paper path wraps it in * the feed-death staleness gate so a plan cannot fire off a dead line. Absent ⇒ the bare provider. */ wrapSeriesProvider?(base: SeriesProvider): SeriesProvider; /** Fold a venue fill into the driver's expected-position ledger (the reconciliation input), called * per fill BEFORE it is fed back to the engine. */ onVenueFill?(fill: OrderEvent): void; /** Run the engine sweep (+ the post-sweep venue-fill feedback) inside the driver's own error boundary * — the paper path maps a wall's `ClampRefused`/`IbkrOrderRefused` throw into a typed session * STAND_DOWN here. Absent ⇒ the sweep runs bare and any throw propagates. */ guardSweep?(apply: () => void): void; } /** What a {@link SessionCore} is constructed from — the pieces both the one-shot * {@link runSimSession} and the stepped {@link import("./day.ts").runDaySession} agree on. */ export interface SessionCoreOptions { readonly meta: MetaEvent; readonly specs: readonly InstrumentSpec[]; readonly fillModel: FillModelName; readonly rUsd: number; readonly fairTauYears: FairTauProvider; readonly makerFairParams?: EpisodeSigmoidParams; /** The initial injected clock (the first bus event's `ts`). */ readonly firstTs: number; /** The author's a57.14 experimental envelope, captured from the run's config (kestrel-5zl.6), stamped on * the graded META at open. Absent for a config-less run (a NO-LLM Backtest / day session) ⇒ no envelope. */ readonly envelope?: ExperimentalEnvelope; /** The FULL `ConfigId` of the run's config (`deriveConfigId(canonicalizeConfig(config))`, kestrel-5zl.6), * stamped on the graded META alongside `envelope` (m9i.2 owner tweak — the seeded RUN identity feeding * `SimRunId`). Supplied under the SAME condition as `envelope`; absent ⇒ no stamp. */ readonly configId?: string; /** The **cell config axis** (`cellConfigId(config)` — the full ConfigId with the `fillSeed` REPLICATE axis * stripped, kestrel-9gu.8.1 / ADR-0016 §3), stamped as `meta.cell_config_id`. Supplied ONLY when it DIVERGES * from {@link configId} (the config carried a `fillSeed`); absent for a seedless run, whose cell axis equals * `config_id` (so the graded bus stays byte-identical). The config axis the grid `cellOf` keys the cell on: * seed-only replicates share it. */ readonly cellConfigId?: string; /** The prior session's {@link SessionCarry} (the multi-session horizon design, kestrel-5zl.16). When present with non-empty * `positions`, this session OPENS with that carried inventory seeded into the fill engine at its * carry-mark basis (emitting an opening `place`+`fill` per lot). **Absent — or an `emptyCarry()` — * seeds nothing, so every existing single-session caller (and a length-1 sequence) is byte-identical * to today's flat open.** The standing-document re-arm is the driver's concern, not the core's. */ readonly openingCarry?: SessionCarry; /** The SamplingConfig fill-realization seed (kestrel-9gu.8.1/.8.3, ADR-0016). Present ⇒ the fill engine * draws CAUSAL sampled fills off a `fillSeed`-keyed per-episode substream; absent ⇒ the sampled channel is * OFF (fail-closed — floor + expected only). Derived from the run's config via `fillSeedOf`. */ readonly fillSeed?: number; /** The owner-recorded sampled-channel qualification claim (kestrel-9gu.8.6 → 9gu.12), derived from the * run's config via `sampledQualificationOf`. Present ⇒ stamped on the graded META and judged by the * headline gate. REFUSED LOUDLY (RUNTIME §8) when structurally contradictory: a claim on an unseeded run * (nothing to qualify) or under an uncalibrated judge (never an uncalibrated headline). Absent — every * run today — ⇒ the gate fails closed and strict-cross floor stays the headline (9gu.8 AC#7). */ readonly sampledQualification?: SampledQualificationClaim; /** The complete regime-scope vocabulary of the tape (kestrel-ocyf), pre-scanned from the full bus by * callers that hold it up front (`runSimSession` / `runSimulateSession`). Threaded to the engine so * `armDocument` can issue the DEFINITIVE dead-on-arrival notice for a regime gate whose scope is * never written on this tape (vs the conditional not-yet-written notice when the future is unknown). */ readonly tapeRegimeScopes?: readonly string[]; /** The clock-honest attestation input (ADR-0040 / kestrel-w7la.1): the driver passes `true` ONLY when * the session ran clocked semantics AND the §4 data-floor verification held (it refuses at open * otherwise, so a constructed core with this flag is an attested one). Stamped as the graded META's * `clock_honest: true`; absent ⇒ latency-blind ⇒ no stamp, byte-identical META. */ readonly clockHonest?: true; /** The LIVE-gate seam (OSS-ADR-0053): a factory that, given the wired core internals, returns the * gate a NON-sim progression (paper/live) routes orders through, plus its venue-fill hooks. Present * ONLY for the paper/live drivers; ABSENT for every sim/day/simulate caller — and when absent the * core builds its reference SimGate over its own fill engine and its per-event pass is byte-identical * to before (the sim corpus never sees this field). The factory is called ONCE at construction, after * canonical state + the emitted stream exist. */ readonly liveGate?: (wiring: LiveGateWiring) => LiveGateBinding; } /** * The sim runtime wired end to end — the ONE place the load-bearing per-event pass lives * (RUNTIME §7). Owns the fill engine (the judge), the emitted stream (determinism substrate), * the Gate, canonical market state, and the {@link PlanEngine}. Documents are armed * incrementally ({@link SessionCore.arm}); {@link SessionCore.step} advances one bus event with * **fills-before-sweep** ordering; {@link SessionCore.settle} cash-settles and drains. Both the * one-shot driver and the stepped day runner drive the identical core, so their emitted streams — * and therefore their determinism hashes — are produced by exactly the same code (no duplicated * event loop to drift). */ export declare class SessionCore { #private; readonly meta: MetaEvent; readonly emitted: EmittedStream; readonly fill: SimFillEngine; /** The instrument-keyed resting-order engine for SPOT/equity orders (ADR-0017, * kestrel-20f.14) — the spot sibling of {@link fill}; the Gate routes an intent with no * strike/right here. Idle (zero events, zero settle outcomes) on an options-only session. */ readonly spotFill: SpotFillEngine; readonly gate: SimGate; readonly engine: PlanEngine; readonly state: CanonicalState; readonly execSpec: InstrumentSpec; readonly signalSpec: InstrumentSpec; constructor(opts: SessionCoreOptions); /** Arm one already-normalized document module (RUNTIME §5). Retained (in arm order) as the source * of the GRADED bus's Instance identity (lineage = the authored name; version = plans_sha256). */ arm(mod: Module, opts?: { synthesizedOrder?: boolean; }): void; /** Cancel a resting order by its real Gate ref on behalf of an agent `cancelOrder` (kestrel-5zl.5 / #3c). * Pins the injected clock and routes through the engine so the engine dump (the wake snapshot's * `resting[]` source) and the emitted bus (the ORDER `cancel`) stay consistent in the SAME snapshot — * never one wake late. Returns whether a resting order was actually removed (fail-closed refuse on a * ref that matches nothing currently resting). */ cancelOrder(ref: string, now: number): boolean; /** FLATTEN an instrument on behalf of an agent `flatten` action (bd if0 / 75n). Pins the injected clock * and routes through the engine, which — for every managing plan holding the instrument — cancels the * plan's resting orders (neutralizing the rolling TP re-post) AND crosses a COVERED close through the * SAME Gate a fired Plan uses (never-naked holds; SELL floored at intrinsic). The gate drains its ORDER * cancel/place onto the emitted stream in the same step, so the wake snapshot's `resting[]` (engine dump) * and `engineLog` (bus projection) agree within one snapshot. Returns the closed contracts + plans * flattened (the driver's audit; a flat book returns `{0,0}` — a clean no-op). */ flatten(instrument: string, now: number): { closedQty: number; plansFlattened: number; }; /** The judge-stamped opening META of this session's GRADED bus (ADR-0011 part B): the input header * plus `fill_model` + `instance` + `fidelity`, self-describing the judge that produced these fills. * A pure derivation of the session inputs (fill model, armed documents, mode) — known at open. */ get gradedMeta(): MetaEvent; /** The canonical GRADED bus: the judge-stamped META (seq 0) + every emitted engine reaction (incl. * the settle-outcome telemetry), re-stamped gap-free from 0 — the self-describing artifact a Blotter * projector consumes, and the bus slice 1's enabling-property proof re-derives totals + support from. */ gradedBus(): BusEvent[]; /** * Project this session's canonical GRADED bus into its {@link Blotter} (kestrel-a57.1 slice 2, * ADR-0011). A pure projection of {@link gradedBus} — the Bus is the truth, the Blotter its * regenerable projection (ADR-0010); no engine-state scrape. The existing {@link EpisodeReport} * (see {@link buildReport}) and the CLI/Ledger stand UNCHANGED beside it — the report→Blotter * unification is a later cleanup. Call at finalize (after {@link settle}), as the driver does. */ blotter(): Blotter; /** Supersede the standing document set at `now` (RUNTIME §5, "document supersession"): de-arm * un-fired plans, halt acquisition + cancel unfilled children, inventory + TP/EXIT ride. The * caller {@link arm}s the replacement immediately after. */ supersede(now: number): void; /** Emit a raw (seq-less) bus event onto the emitted stream — the day driver's CONTROL/WAKE * handshake records (never ORDER; those come from the gate/fill engine). */ emit(ev: NewBusEvent): BusEvent; /** * Advance one bus event with the load-bearing ordering (RUNTIME §7): pin the clock, fold * canonical state, then — on a BOOK event — reassess resting orders for fills (the market acts * FIRST, fills fed back into the engine) BEFORE the engine sweep reacts to that same book. */ step(ev: BusEvent): void; /** Cash-settle at the final exec spot (RUNTIME §6): held OPTION inventory → intrinsic; held * SPOT inventory → mark-to-final-spot (ADR-0017 — no expiry, no intrinsic; the mark carries the * kestrel-xwf as-of watermark, so a stale final print is flagged, never silently marked to); * resting → $0. Threads the settle mark's provenance so the settle spot never grades without its * as-of/staleness verdict (kestrel-xwf). Drains the expired-unfilled cancels + settle telemetry * onto the emitted stream. Call once, * after the last step. * * `opts.carry` (the multi-session horizon design, kestrel-5zl.16.3) — a NON-final session of a multi-session Instance — * marks held OPTION inventory to close and lets it SURVIVE into {@link carriedInventory} (the emitted bus is * byte-identical to an intrinsic settle; only the bus-silent carried hand-off differs). Absent / `false` * — the final or a standalone session — is today's terminal intrinsic settle exactly (the position dies), * so a length-1 sequence is byte-for-byte unchanged. SPOT inventory carry (the overnight equity swing) is * NOT built yet (kestrel-20f.8): a carry settle that would strand a net spot position REFUSES loudly * rather than silently terminal-marking it (fail-closed, RUNTIME §8); a flat/closed spot book carries fine. * * kestrel-xwf: the mark's provenance is threaded to the engine, which grades it fail-closed (stale = * unstated as-of OR older than the declared threshold) and — when STALE — applies the closing * put-call-parity candidate derived here from the last folded two-sided book of the exec symbol * (the ANNOTATED recovery: `source: "parity"`, the book settles against the recovered spot) or * honestly refuses (`source: "stale"`, mark-uncertain, the last mark retained). The unified * `settle_mark` TELEMETRY record rides the graded bus whenever at least one order settled. */ settle(opts?: { readonly carry?: boolean; }): ReturnType; /** The carry-mark lots a `settle({ carry: true })` marked-and-kept — this session's contribution to the * next session's opening book (the multi-session horizon design). Empty after a final / intrinsic settle. */ carriedInventory(): readonly CarriedLot[]; /** The spot settle report (mark-to-final-spot, ADR-0017), after {@link settle}. Empty outcomes * on an options-only session. */ get spotSettle(): SpotSettleReport | undefined; /** The standing AUTHORED module at session end — the last authored View/Wake/Plan book (the carried * standing document, re-armed fresh next session), or `undefined` if this session authored no book * (synthesized one-shot orders do not count). */ get standingModule(): Module | undefined; /** Every armed plan STATEMENT the core holds, in arm order (kestrel-wa0j.29) — the typed ASTs the sim * driver captures the ENFORCED terms from for the `armed-plan` pane (the watcher's role-keyed percept: * it manages plans whose document text it otherwise never sees). A read-only projection of the armed * module set — it holds the SAME ASTs the engine armed, never a re-parse. */ get armedPlanStatements(): readonly PlanStatement[]; /** The resolved settle-mark provenance + verdict + annotated recovery (kestrel-xwf), available * after {@link settle} (the engine's {@link SettleMark}, unchanged). */ get settleMark(): SettleMark | undefined; /** Build the graded report (after {@link settle}). `busEventCount` and `busSha256` pin the * input bus alongside the emitted-stream determinism hash (F6). */ buildReport(busEventCount: number, busSha256: string): EpisodeReport; /** The latest folded option book per instrument — the chain a Frame renders. */ get books(): ReadonlyMap; /** The current injected clock (the last stepped event's `ts`, or `firstTs` before any step). */ get settleTs(): number; } export { requireMeta, resolveSpecs, specFromMeta }; /** The sha256 of the serialized input bus — pins WHAT a run was graded against (F6). */ export declare function busSha256Of(events: readonly BusEvent[]): string; /** The tape's complete regime-scope vocabulary (kestrel-ocyf): every scope any REGIME event on the * bus writes, de-duplicated. Callers holding the full bus pass this to the engine so `armDocument` * can prove a regime gate dead on arrival (scope outside this set ⇒ it can never arm on this tape). */ export declare function tapeRegimeScopesOf(events: readonly BusEvent[]): string[]; /** * Drive one `sim` session end to end and return its graded {@link EpisodeReport} (RUNTIME §7). * Pure with respect to its inputs (given `events`, no I/O at all); with `busPath` it reads the * bus once. If `out` is given, the report is also written there as pretty JSON. Fails closed on * a missing META, an unknown fill model, or no instruments (RUNTIME §8). A thin driver over * {@link SessionCore}: arm all documents up front, step every event, settle, build. */ export declare function runSimSession(opts: RunSimOptions): EpisodeReport; /** Serialize + write a report to a path as pretty JSON (used by {@link runSimSession}'s `out` * and the CLI). */ export declare function writeReport(path: string, report: EpisodeReport): void; //# sourceMappingURL=sim.d.ts.map