@insiderfinance/totalfinance 0.1.0

package/modules/backtest/src/execution/index.ts

@@ -0,0 +1,91 @@
+/**
+ * `@insiderfinance/totalfinance/backtest/execution` — pluggable execution reality (Stage 4.6, FC8 Decision 7).
+ *
+ * - {@link execution} — `simplified()` (the honest default; its label says exactly what it does)
+ *   and `declared()` (every member the caller states, validated, under a label the caller signs).
+ * - {@link fillModels} — the built-in bar, quote, and order-book fill models; {@link barTriggerPrice}
+ *   is the bar touch rule the shipped `SimulatedBroker` applies, exported so the two never drift.
+ * - {@link orderTouchSequence} — the four intrabar ambiguity policies over one bar's touches.
+ * - {@link spreadModels}, {@link impactModels}, {@link latencyModels} and the re-exported
+ *   {@link fees}, {@link slippage}, {@link borrow} — small named cost models.
+ * - {@link requiredInitialMargin}, {@link maintenanceMarginBreached}, and the closed guards
+ *   {@link requireOrderIntent}, {@link requireFillDecision}, {@link requireMarketObservation},
+ *   {@link requireFillContext}, {@link requireExecutionPolicy}, {@link requireMarginPolicy}.
+ * - {@link assertFillModelConformance} — what a custom fill model must satisfy.
+ * - {@link normalizedFillFromDecision} — a filled decision → the portfolio-owned `NormalizedFill`.
+ * - {@link describeExecutionPolicy} — the JSON-safe projection every result echoes.
+ *
+ * Nothing here computes a P&L, a position, or a mark; those are the ledger's and the engines'.
+ */
+
+export {
+  borrow,
+  describeExecutionPolicy,
+  execution,
+  fees,
+  impactModels,
+  latencyModels,
+  maintenanceMarginBreached,
+  requiredInitialMargin,
+  slippage,
+  spreadModels,
+} from './policy.js';
+export {
+  requireExecutionPolicy,
+  requireFillContext,
+  requireFillDecision,
+  requireMarginPolicy,
+  requireMarketObservation,
+  requireOrderIntent,
+} from './validate.js';
+export type { DeclaredExecutionPolicy } from './policy.js';
+export { barTriggerPrice, fillModels } from './fill-models.js';
+export { orderTouchSequence } from './intrabar.js';
+export type {
+  IntrabarPath,
+  IntrabarTouch,
+  OrderTouchSequenceInput,
+  OrderTouchSequenceResult,
+} from './intrabar.js';
+export { assertFillModelConformance } from './conformance.js';
+export type {
+  AssertFillModelConformanceInput,
+  FillModelConformanceResult,
+  FillModelFixture,
+} from './conformance.js';
+export { normalizedFillFromDecision, normalizedFillsFromBacktest } from './normalized.js';
+export { fillOrderWithPolicy } from './fill-order.js';
+export type { FillOrderWithPolicyInput, FillOrderWithPolicyResult } from './fill-order.js';
+export type {
+  NormalizedFillFromDecisionInput,
+  NormalizedFillsFromBacktestInput,
+} from './normalized.js';
+export type {
+  AmbiguityPolicy,
+  ExecutionCosts,
+  OrderType,
+  ExecutionPolicy,
+  ExecutionPolicyDescription,
+  TimeInForce,
+  FillContext,
+  FillDecision,
+  FillModel,
+  FillRequest,
+  ForcedLiquidationPolicy,
+  HaltWindow,
+  LatencyModel,
+  LockedCrossedPolicy,
+  MarginPolicy,
+  MarketImpactModel,
+  MarketObservation,
+  MarketObservationKind,
+  OrderIntent,
+  OrderSide,
+  PartialFillPolicy,
+  PriceLimitWindow,
+  QueueModel,
+  SessionRules,
+  SpreadModel,
+  StaleQuotePolicy,
+  UnfilledReason,
+} from './types.js';

package/modules/backtest/src/execution/intrabar.ts

@@ -0,0 +1,185 @@
+/**
+ * Intrabar ambiguity (Stage 4.6, FC8 Decision 7). A bar says where prices went, not in which
+ * order. When two orders could both have touched inside one bar — a take-profit above and a
+ * stop-loss below, two resting orders on opposite sides of the open — the sequence is a decision
+ * the run must make explicitly. Four policies, one function, and the count of ambiguous bars in
+ * every result's diagnostics.
+ */
+
+import {
+  ErrorCode,
+  InputError,
+  ensureKnownKeys,
+  requireArgumentArray,
+  requireArgumentObject,
+} from '@totalfinance/core';
+import type { AmbiguityPolicy } from './types.js';
+
+/** One order that touched inside the bar. */
+export interface IntrabarTouch {
+  orderId: string;
+  /** The price at which the order would fill. */
+  triggerPrice: number;
+  /** Whether filling this order first is the favorable sequence for the account (a take-profit). */
+  favorable: boolean;
+}
+
+export interface OrderTouchSequenceInput {
+  bar: { open: number; high: number; low: number; close: number };
+  touches: readonly IntrabarTouch[];
+  policy: AmbiguityPolicy;
+}
+
+export type IntrabarPath = 'open-low-high-close' | 'open-high-low-close' | 'unambiguous';
+
+export interface OrderTouchSequenceResult {
+  /** Order ids in fill sequence. */
+  sequence: string[];
+  /** The path the sequence assumes; `unambiguous` when every touch lay on one side of the open. */
+  path: IntrabarPath;
+  /** Whether the bar alone could not decide the sequence (the policy did). */
+  ambiguous: boolean;
+  policy: AmbiguityPolicy;
+}
+
+const INPUT_KEYS = ['bar', 'touches', 'policy'] as const;
+const TOUCH_KEYS = ['orderId', 'triggerPrice', 'favorable'] as const;
+const POLICIES: readonly AmbiguityPolicy[] = [
+  'optimistic',
+  'pessimistic',
+  'deterministic-path',
+  'reject',
+];
+
+function distanceOrder(touches: readonly IntrabarTouch[], open: number): string[] {
+  // Nearer the open fills first; ties break on orderId so the sequence is stable.
+  return [...touches]
+    .sort(
+      (a, b) =>
+        Math.abs(a.triggerPrice - open) - Math.abs(b.triggerPrice - open) ||
+        (a.orderId < b.orderId ? -1 : a.orderId > b.orderId ? 1 : 0),
+    )
+    .map((touch) => touch.orderId);
+}
+
+/**
+ * Resolve the fill sequence of the orders a bar touched. Touches on one side of the open are
+ * never ambiguous (nearer the open fills first). Touches on both sides are: `deterministic-path`
+ * walks open → low → high → close on an up bar (close ≥ open) and open → high → low → close on a
+ * down bar; `optimistic` walks the side holding a favorable touch first (and the deterministic
+ * path when both sides do); `pessimistic` the reverse; `reject` refuses with
+ * `backtest.ambiguous_intrabar` naming the orders.
+ */
+export function orderTouchSequence(input: OrderTouchSequenceInput): OrderTouchSequenceResult {
+  const functionName = 'orderTouchSequence';
+  requireArgumentObject(functionName, 'input', input);
+  ensureKnownKeys(functionName, 'input', input, INPUT_KEYS);
+  requireArgumentObject(functionName, 'input.bar', input.bar);
+  for (const field of ['open', 'high', 'low', 'close'] as const) {
+    const value = input.bar[field];
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      throw new InputError(`${functionName}: input.bar.${field} must be a finite number.`, {
+        code: ErrorCode.InputWrongType,
+        context: { field: `bar.${field}` },
+      });
+    }
+  }
+  if (input.bar.low > input.bar.high) {
+    throw new InputError(
+      `${functionName}: input.bar.low (${input.bar.low}) exceeds input.bar.high (${input.bar.high}).`,
+      { code: ErrorCode.InputOutOfRange, context: { field: 'bar.low' } },
+    );
+  }
+  requireArgumentArray(functionName, 'input.touches', input.touches);
+  const ids = new Set<string>();
+  input.touches.forEach((touch, index) => {
+    const path = `input.touches[${index}]`;
+    requireArgumentObject(functionName, path, touch);
+    ensureKnownKeys(functionName, path, touch, TOUCH_KEYS);
+    if (typeof touch.orderId !== 'string' || touch.orderId.length === 0) {
+      throw new InputError(`${functionName}: ${path}.orderId must be a non-empty string.`, {
+        code: ErrorCode.InputWrongType,
+        context: { field: `${path}.orderId` },
+      });
+    }
+    if (ids.has(touch.orderId)) {
+      throw new InputError(
+        `${functionName}: ${path}.orderId '${touch.orderId}' repeats an earlier touch.`,
+        {
+          code: ErrorCode.InputOutOfRange,
+          context: { field: `${path}.orderId` },
+        },
+      );
+    }
+    ids.add(touch.orderId);
+    if (typeof touch.triggerPrice !== 'number' || !Number.isFinite(touch.triggerPrice)) {
+      throw new InputError(`${functionName}: ${path}.triggerPrice must be a finite number.`, {
+        code: ErrorCode.InputWrongType,
+        context: { field: `${path}.triggerPrice` },
+      });
+    }
+    if (touch.triggerPrice < input.bar.low || touch.triggerPrice > input.bar.high) {
+      throw new InputError(
+        `${functionName}: ${path}.triggerPrice (${touch.triggerPrice}) lies outside the bar's range [${input.bar.low}, ${input.bar.high}] — a touch the bar never made is not a touch.`,
+        { code: ErrorCode.InputOutOfRange, context: { field: `${path}.triggerPrice` } },
+      );
+    }
+    if (typeof touch.favorable !== 'boolean') {
+      throw new InputError(`${functionName}: ${path}.favorable must be a boolean.`, {
+        code: ErrorCode.InputWrongType,
+        context: { field: `${path}.favorable` },
+      });
+    }
+  });
+  if (!POLICIES.includes(input.policy)) {
+    throw new InputError(
+      `${functionName}: input.policy must be one of ${POLICIES.map((p) => `'${p}'`).join(' | ')}. Received ${JSON.stringify(input.policy)}.`,
+      { code: ErrorCode.InputInvalidEnum, context: { field: 'policy' } },
+    );
+  }
+  const { open, close } = input.bar;
+  const above = input.touches.filter((touch) => touch.triggerPrice > open);
+  const below = input.touches.filter((touch) => touch.triggerPrice < open);
+  const atOpen = input.touches.filter((touch) => touch.triggerPrice === open);
+  const atOpenIds = distanceOrder(atOpen, open);
+  if (above.length === 0 || below.length === 0) {
+    return {
+      sequence: [...atOpenIds, ...distanceOrder(above.length > 0 ? above : below, open)],
+      path: 'unambiguous',
+      ambiguous: false,
+      policy: input.policy,
+    };
+  }
+  if (input.policy === 'reject') {
+    throw new InputError(
+      `${functionName}: the bar (open ${open}, high ${input.bar.high}, low ${input.bar.low}, close ${close}) touched orders on both sides of the open — ${above.map((t) => t.orderId).join(', ')} above and ${below.map((t) => t.orderId).join(', ')} below — and the 'reject' ambiguity policy refuses to choose a sequence. Choose 'optimistic', 'pessimistic', or 'deterministic-path', or supply finer observations.`,
+      {
+        code: ErrorCode.BacktestAmbiguousIntrabar,
+        context: { above: above.map((t) => t.orderId), below: below.map((t) => t.orderId) },
+      },
+    );
+  }
+  const deterministic: IntrabarPath = close >= open ? 'open-low-high-close' : 'open-high-low-close';
+  let path: IntrabarPath = deterministic;
+  if (input.policy === 'optimistic' || input.policy === 'pessimistic') {
+    const favorableAbove = above.some((t) => t.favorable);
+    const favorableBelow = below.some((t) => t.favorable);
+    if (favorableAbove !== favorableBelow) {
+      const favorableSideFirst: IntrabarPath = favorableAbove
+        ? 'open-high-low-close'
+        : 'open-low-high-close';
+      const unfavorableSideFirst: IntrabarPath = favorableAbove
+        ? 'open-low-high-close'
+        : 'open-high-low-close';
+      path = input.policy === 'optimistic' ? favorableSideFirst : unfavorableSideFirst;
+    }
+  }
+  const first = path === 'open-low-high-close' ? below : above;
+  const second = path === 'open-low-high-close' ? above : below;
+  return {
+    sequence: [...atOpenIds, ...distanceOrder(first, open), ...distanceOrder(second, open)],
+    path,
+    ambiguous: true,
+    policy: input.policy,
+  };
+}

package/modules/backtest/src/execution/normalized.ts

@@ -0,0 +1,216 @@
+/**
+ * From a fill decision to the ledger's fill (Stage 4.6, FC8 Decision 2). A simulator that filled an
+ * order calls this to produce the portfolio-owned {@link NormalizedFill}; the ledger's own
+ * `portfolioEventsFromFill` then turns it into economic events. The backtest package never defines
+ * a fill of its own.
+ */
+
+import type { EpochMs } from '@totalfinance/core';
+import type { Trade } from '../types.js';
+import { ErrorCode, InputError, ensureKnownKeys, requireArgumentObject } from '@totalfinance/core';
+import { type NormalizedFill, requireNormalizedFill } from '@totalfinance/portfolio';
+import type { FillDecision, OrderIntent } from './types.js';
+import { hasOwn, requireFillDecision, requireOrderIntent } from './validate.js';
+
+export interface NormalizedFillFromDecisionInput {
+  decision: FillDecision;
+  order: OrderIntent;
+  accountId: string;
+  currency: string;
+  filledTimestampMs: EpochMs;
+  /** Defaults to `<orderId>:fill`; a partial fill sequence should number its fills. */
+  fillId?: string;
+  costs?: NormalizedFill['costs'];
+  /** Attribution already included in the execution price, not an additional cash charge. */
+  executionPriceAdjustment?: NormalizedFill['executionPriceAdjustment'];
+  settleTimestampMs?: EpochMs;
+  contractMultiplier?: number;
+  settlementStyle?: NormalizedFill['settlementStyle'];
+  contract?: NormalizedFill['contract'];
+  accruedInterest?: number;
+  venue?: string;
+  liquidity?: NormalizedFill['liquidity'];
+}
+
+/** A deep copy of plain JSON data (the only kind these boundaries accept); typed, lib-free. */
+function cloneJson<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+const KEYS = [
+  'decision',
+  'order',
+  'accountId',
+  'currency',
+  'filledTimestampMs',
+  'fillId',
+  'costs',
+  'executionPriceAdjustment',
+  'settleTimestampMs',
+  'contractMultiplier',
+  'settlementStyle',
+  'contract',
+  'accruedInterest',
+  'venue',
+  'liquidity',
+] as const;
+
+/** Build the portfolio-owned fill for a filled decision; an unfilled decision is a teaching refusal. */
+export function normalizedFillFromDecision(input: NormalizedFillFromDecisionInput): NormalizedFill {
+  const functionName = 'normalizedFillFromDecision';
+  requireArgumentObject(functionName, 'input', input);
+  ensureKnownKeys(functionName, 'input', input, KEYS);
+  requireFillDecision(functionName, 'input.decision', input.decision);
+  requireOrderIntent(functionName, 'input.order', input.order);
+  // Optional members are present-or-absent; a present null is a refusal, never a silent default.
+  for (const key of KEYS) {
+    if (hasOwn(input, key) && (input as unknown as Record<string, unknown>)[key] === null) {
+      throw new InputError(
+        `${functionName}: input.${key} is null — omit the field to leave it unset; null is not a value here.`,
+        { code: ErrorCode.InputWrongType, context: { field: key } },
+      );
+    }
+  }
+  if (hasOwn(input, 'fillId') && (typeof input.fillId !== 'string' || input.fillId.length === 0)) {
+    throw new InputError(`${functionName}: input.fillId must be a non-empty string when given.`, {
+      code: ErrorCode.InputWrongType,
+      context: { field: 'fillId' },
+    });
+  }
+  if (input.decision.outcome !== 'filled') {
+    throw new InputError(
+      `${functionName}: input.decision is not a fill (outcome ${JSON.stringify((input.decision as { outcome?: unknown }).outcome)}${'reason' in input.decision ? `, reason '${String(input.decision.reason)}'` : ''}) — only a filled decision becomes a ledger fill.`,
+      {
+        code: ErrorCode.InputOutOfRange,
+        context: { field: 'decision.outcome', orderId: input.order.orderId },
+      },
+    );
+  }
+  const fill: NormalizedFill = {
+    fillId: input.fillId ?? `${input.order.orderId}:fill`,
+    accountId: input.accountId,
+    instrumentId: input.order.instrumentId,
+    side: input.order.side,
+    quantity: input.decision.quantity,
+    pricePerUnit: input.decision.pricePerUnit,
+    currency: input.currency,
+    filledTimestampMs: input.filledTimestampMs,
+    orderId: input.order.orderId,
+    ...(input.settleTimestampMs !== undefined
+      ? { settleTimestampMs: input.settleTimestampMs }
+      : {}),
+    ...(input.contractMultiplier !== undefined
+      ? { contractMultiplier: input.contractMultiplier }
+      : {}),
+    ...(input.settlementStyle !== undefined ? { settlementStyle: input.settlementStyle } : {}),
+    ...(input.contract !== undefined ? { contract: cloneJson(input.contract) } : {}),
+    ...(input.accruedInterest !== undefined ? { accruedInterest: input.accruedInterest } : {}),
+    ...(input.costs !== undefined ? { costs: { ...input.costs } } : {}),
+    ...(input.executionPriceAdjustment !== undefined
+      ? { executionPriceAdjustment: input.executionPriceAdjustment }
+      : {}),
+    ...(input.venue !== undefined ? { venue: input.venue } : {}),
+    ...(input.liquidity !== undefined ? { liquidity: input.liquidity } : {}),
+  };
+  requireNormalizedFill(functionName, 'fill', fill);
+  return fill;
+}
+
+/** Input for {@link normalizedFillsFromBacktest}: the trades a backtest reported, and the account they book to. */
+export interface NormalizedFillsFromBacktestInput {
+  /** The run's trades (`result.trades`), in order. */
+  trades: readonly Trade[];
+  accountId: string;
+  /** The currency every fill books in (a backtest quotes one currency). */
+  currency: string;
+  /** Fill ids default to `<sourceId>:fill:<n>`; the source names the run. */
+  sourceId: string;
+  /** Instrument terms by symbol (an option's contract, its settlement style) for fills that need them. */
+  instruments?: Readonly<
+    Record<
+      string,
+      {
+        contract?: NormalizedFill['contract'];
+        settlementStyle?: NormalizedFill['settlementStyle'];
+        settleTimestampMs?: EpochMs;
+      }
+    >
+  >;
+}
+
+const FROM_BACKTEST_KEYS = ['trades', 'accountId', 'currency', 'sourceId', 'instruments'] as const;
+
+/**
+ * B6 — the bridge from a backtest's trades to the ledger's fills: one `NormalizedFill` per trade,
+ * keyed by `instrumentId = symbol`, the contract multiplier the engine stamped, commission and
+ * commission as a cash cost. Slippage is already in trade.price; trade.slippage is attribution,
+ * not another cash charge. Every fill is validated by the ledger's own guard, so a run's trades fold
+ * through `portfolioEventsFromFill` exactly like a paper broker's.
+ */
+export function normalizedFillsFromBacktest(
+  input: NormalizedFillsFromBacktestInput,
+): NormalizedFill[] {
+  const functionName = 'normalizedFillsFromBacktest';
+  requireArgumentObject(functionName, 'input', input);
+  ensureKnownKeys(functionName, 'input', input, FROM_BACKTEST_KEYS);
+  if (!Array.isArray(input.trades)) {
+    throw new InputError(`${functionName}: input.trades must be an array of backtest trades.`, {
+      code: ErrorCode.InputWrongType,
+      context: { field: 'trades' },
+    });
+  }
+  for (const key of ['accountId', 'currency', 'sourceId'] as const) {
+    if (typeof input[key] !== 'string' || input[key].length === 0) {
+      throw new InputError(`${functionName}: input.${key} must be a non-empty string.`, {
+        code: ErrorCode.InputWrongType,
+        context: { field: key },
+      });
+    }
+  }
+  if (input.instruments !== undefined)
+    requireArgumentObject(functionName, 'input.instruments', input.instruments);
+  return input.trades.map((trade, index) => {
+    requireArgumentObject(functionName, `input.trades[${index}]`, trade);
+    for (const key of ['commission', 'slippage'] as const) {
+      if (typeof trade[key] !== 'number' || !Number.isFinite(trade[key]) || trade[key] < 0)
+        throw new InputError(
+          `${functionName}: input.trades[${index}].${key} must be a finite non-negative amount in the trade currency.`,
+          {
+            code:
+              typeof trade[key] !== 'number'
+                ? ErrorCode.InputWrongType
+                : !Number.isFinite(trade[key])
+                  ? ErrorCode.InputNotFinite
+                  : ErrorCode.InputOutOfRange,
+            context: { function: functionName, field: `input.trades[${index}].${key}` },
+          },
+        );
+    }
+    const terms = input.instruments?.[trade.symbol];
+    const costs: NonNullable<NormalizedFill['costs']> = {
+      ...(trade.commission > 0 ? { commission: trade.commission } : {}),
+    };
+    const fill: NormalizedFill = {
+      fillId: `${input.sourceId}:fill:${index + 1}`,
+      accountId: input.accountId,
+      instrumentId: trade.symbol,
+      side: trade.side,
+      quantity: trade.quantity,
+      pricePerUnit: trade.price,
+      currency: input.currency,
+      filledTimestampMs: trade.timestampMs,
+      ...(trade.multiplier !== 1 ? { contractMultiplier: trade.multiplier } : {}),
+      ...(terms?.contract !== undefined
+        ? { contract: cloneJson(terms.contract), contractMultiplier: trade.multiplier }
+        : {}),
+      ...(terms?.settlementStyle !== undefined ? { settlementStyle: terms.settlementStyle } : {}),
+      ...(terms?.settleTimestampMs !== undefined
+        ? { settleTimestampMs: terms.settleTimestampMs }
+        : {}),
+      ...(Object.keys(costs).length > 0 ? { costs } : {}),
+      ...(trade.slippage !== 0 ? { executionPriceAdjustment: trade.slippage } : {}),
+    };
+    requireNormalizedFill(functionName, `fills[${index}]`, fill);
+    return fill;
+  });
+}