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

/**
 * # series — canonical state, window series, and the tri-state causal trigger evaluator
 *
 * Charter: anything with a name whose value changes over time is a **series** — the
 * universal operand of the language (CONTEXT: Series, Registry). There are exactly two
 * kinds and only two: **market facts** (ambient per signal instrument, spectator-visible)
 * and **org facts** (path-scoped in the pod tree, acting-sessions only). An unresolvable
 * series reads **UNKNOWN** and de-arms its referencing statement with a logged reason —
 * never crashing, never silently reading false (RUNTIME §2/§3/§8).
 *
 * This milestone implements the market-fact substrate + the evaluator (RUNTIME §2–§3):
 *
 * - {@link CanonicalState} — one causal coordinate per signal instrument (`spot`, `hod`,
 *   `lod`, opening range, `vwap`, `prior_close`, session phase), updated ONLY via
 *   {@link CanonicalState.applyEvent}. State at event *N* is a pure function of events ≤ *N*.
 * - {@link WindowEngine} — the windowed magnitude/rate series (`velocity`, `move`, `range`,
 *   each `$/window` and `%/window`) over a spot ring buffer, with trailing `p*`/`sigma`
 *   baselines. UNKNOWN until warm.
 * - {@link SeriesProvider} / {@link CanonicalSeriesProvider} — resolve a `SeriesRef` (from
 *   `src/lang`) to a value; market facts from canonical state, org facts via the injected
 *   {@link OrgFacts} (the engine supplies the real one; {@link FakeOrgFacts} is the test
 *   double).
 * - {@link TriggerEvaluator} — evaluate a `Trigger` to `true | false | UNKNOWN` with
 *   per-node causal memory owned by the armed statement instance (crosses need a transition,
 *   `held` anchors continuity, `within` anchors at the event); only a definite `true` fires.
 * - {@link SeriesRegistry} — the one shared phonebook (CONTEXT: Registry): one registration
 *   record per series name (kind, scope, window semantics), platform-declared for market facts
 *   and implicitly registered for org facts. The provider dials it for market-vs-org routing.
 *
 * The `UNKNOWN` sentinel and the `durationMs` units bridge live in {@link ./types.ts}.
 */

export {
  UNKNOWN,
  isUnknown,
  isNumber,
  durationMs,
  type Unknown,
  type SeriesValue,
  type Resolved,
  type TriState,
} from "./types.ts";

export {
  WindowEngine,
  type WindowMetric,
  type WindowValue,
  type BaselineStat,
  type WindowConfig,
} from "./windows.ts";

export {
  CanonicalState,
  type CanonicalStateConfig,
  type Stamped,
} from "./state.ts";

export {
  CanonicalSeriesProvider,
  FakeOrgFacts,
  pathKey,
  type SeriesProvider,
  type OrgFacts,
  type CanonicalProviderHooks,
} from "./provider.ts";

export {
  TriggerEvaluator,
  type NodeMem,
  type EvaluatorState,
} from "./trigger.ts";

export {
  unknownSeriesDiagnostic,
  type UnknownSeriesDiagnostic,
} from "./author-lint.ts";

export {
  SeriesRegistry,
  defaultSeriesRegistry,
  PLATFORM_SERIES,
  OBSERVABILITY_ORDER,
  isFinerThanFidelity,
  type SeriesRegistration,
  type SeriesKind,
  type Windowing,
  type SeriesScope,
  type SeriesUnit,
  type ObservabilityClass,
  type GradingFidelity,
  type SeriesAdmission,
  type MarketBinding,
  type MarketScalar,
  type RegistrationSource,
} from "./registry.ts";