kestrel.markets/src/engine/index.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.

/**
 * # engine — the rule engine, canonical market state, and ExecutionFair
 *
 * Charter: the tick loop. It evaluates armed Wake/Plan triggers each tick over
 * detectors and series computed causally from the stream it already owns (never a
 * second market-data connection); on a confirmed trigger it fires the pre-authorized
 * action through the **Gate** and wakes L2 in parallel (**fire-then-inform**).
 * Deterministic and replayable: the same input sequence yields the same event sequence.
 * It hosts the **canonical market state** — one causal coordinate per underlying (spot,
 * HOD/LOD, opening range, velocity, structural levels) sourced from the deepest
 * instrument, health-gated, degrading explicitly rather than reconciling two estimates —
 * and **ExecutionFair**, the `@fair` anchor: the honest price a market maker will fill
 * you at (underlying-anchored intrinsic + a vol read backed out of the *liquid* quotes,
 * floored at intrinsic), receipt-gated for trust. The observed mid is a health signal,
 * never a value. Belief is the author's; fair is the engine's.
 *
 * (Phase 1: charter only. The rule engine / canonical state / ExecutionFair wiring lands in a
 * later milestone. Price resolution — the pure layer between a parsed price line and a concrete
 * order intent — ships first, in {@link ./pricing.ts}, RUNTIME §4.)
 */

export {
  resolvePrice,
  isUnresolvable,
  type PriceLine,
  type PriceCtx,
  type PriceResolution,
  type PriorResolution,
  type RepriceTokenBucket,
} from "./pricing.ts";

export {
  PlanEngine,
  deriveOrderGuard,
  ArmError,
  armRefusalError,
  ARM_BOUND_NOTHING_MARKER,
  type PlanEngineOptions,
  type OrderIntent,
  type OrderGuardEvidence,
  type OrderRole,
  type Gate,
  type BusSink,
  type InstrumentSpec,
} from "./plans.ts";

export { BookLedger, EngineOrgFacts, type LedgerFill, type MultiplierOf } from "./orgfacts.ts";

// The arm-level validation surface (kestrel-bc38.2): parse + arm-time integrity WITHOUT running a
// session, returning tiered diagnostics. The shared preview for consumers with NO live core (docs
// arm-gate, hosted /validate, an agent's construct-time check) — the refusal is byte-identical across a
// 422 and a run because it drives the engine's real `armDocument`. It validates against a FRESH engine,
// so it cannot see live-book guards (F4 same-name collision): `day.ts` keeps its own `previewSupersede`
// through the live core, and must not be migrated here. See the header of ./validate.ts.
export {
  validateArm,
  type ArmContext,
  type ArmValidation,
  type ArmDiagnostic,
  type ArmDiagnosticTier,
} from "./validate.ts";

// ─────────────────────────────────────────────────────────────────────────────
// The stable, NAMESPACED engine surface (kestrel-djm.3)
// ─────────────────────────────────────────────────────────────────────────────
//
// This barrel is the local-execution capability aggregate the package publishes as
// the `./engine` subpath (and, hung under one key, as `engine` on the root barrel —
// see `src/index.ts`). The rule-engine's OWN exports above (PlanEngine, ExecutionFair
// pricing, the BookLedger) are ONE component reached THROUGH these capabilities (a
// Session drives them); the seven aggregate namespaces below are the published surface
// local Session/Grade consumers and the SDK (kestrel-djm.5) bind to instead of deep
// private paths. `canonical` is the newest: the ONE canonical-JSON + content-hash owner
// (kestrel-zs2f), published here so the PLATFORM imports the SAME bytes for cross-repo
// certification instead of reimplementing them (kestrel-markets-5l3).
//
// Each capability rides under its OWN namespace so the engine tree's domain types
// (`Position`/`Instrument` in `frame/types.ts` + `lang/ast.ts`) never collide with the
// protocol's generic ones or with each other in a flat re-export — the ambiguity the
// `src/index.ts` note warns about. A namespaced import is imported separately, so there
// is no cross-capability name clash by construction.
//
// LIGHT/HEAVY seam: NONE of these seven barrels value-imports `bun:sqlite` / `chdb` /
// the lake / the run ledger — those live only behind `src/ledger/index.ts`,
// `src/adapters/lake/index.ts`, `src/session/cli.ts`, and the CLI's lazy
// `src/cli/heavy.ts`, none of which are on these barrels (pinned by
// `tests/package.boundary.test.ts`). The engine surface DOES use Bun/node runtime
// globals (`Bun.*`, `node:fs`), so it is the HEAVY, Bun-hosted local path — distinct
// from the zero-built-in `./protocol` and `./client` faces, which stay light.
//
// `frame` is present but callable-empty at runtime: `src/frame/index.ts` is types-only
// by charter (the render fns live in `frame/render.ts`), so the namespace object exists
// (the materialization contract) while carrying no runtime binding.
export * as lang from "../lang/index.ts";
export * as frame from "../frame/index.ts";
export * as session from "../session/index.ts";
export * as fill from "../fill/index.ts";
export * as blotter from "../blotter/index.ts";
export * as grade from "../grade/index.ts";
export * as canonical from "../canonical/index.ts";