@insiderfinance/totalfinance 0.1.0

package/modules/backtest/dist/event-driven.js

@@ -0,0 +1,325 @@
+/**
+ * Event-driven execution backtest engine (spec §16.2).
+ *
+ * A chronological event loop over multi-symbol bars. A `strategy(context)` registers per-symbol bar
+ * handlers and streaming indicators; on each bar the engine fills the previous bar's orders, updates
+ * indicators, then runs the handler — which may submit new orders that fill on the *next* bar. This
+ * one-bar lag is the no-look-ahead contract: a strategy never trades on a price it has already seen.
+ *
+ *   backtest.eventDriven({ data, broker: brokers.simulated({ cash: 1e5 }), strategy(context) {
+ *     const fast = context.indicator('AAPL', technicalAnalysis.sma.stream({ period: 20 }), 'close');
+ *     const slow = context.indicator('AAPL', technicalAnalysis.sma.stream({ period: 50 }), 'close');
+ *     context.onBar('AAPL', () => {
+ *       if (crossOver(fast, slow)) context.buy('AAPL', { percent: 1 });
+ *       if (crossUnder(fast, slow)) context.close('AAPL');
+ *     });
+ *   }});
+ */
+import { CONVENTIONS_VERSION, ErrorCode, InputError, ensureFinite, ensureKnownKeys, ensurePositive, missingFieldError, requireArgumentObject, sideOf, signOf, WarningCode, } from '../../core/dist/index.js';
+import { analyze } from '../../performance/dist/index.js';
+import { SimulatedBroker, } from './broker.js';
+import { equityToReturns } from './vectorized.js';
+import { checkDataAlignment } from './diagnostics.js';
+import { requireBarData } from './validate.js';
+import { BENCHMARK_FIXTURE_VERSION, toEquityPoints, tradeNotional, } from './types.js';
+function requireNumericHandle(functionName, field, handle) {
+    requireArgumentObject(functionName, field, handle);
+    for (const key of ['value', 'previous']) {
+        const value = handle[key];
+        if (value === undefined) {
+            throw missingFieldError(functionName, `${field}.${key}`, `${functionName}({ value: 2, previous: 1 }, { value: 1, previous: 1 })`);
+        }
+        if (value !== null)
+            ensureFinite(value, `${field}.${key}`, functionName);
+    }
+}
+/** True when series `a` crosses from at-or-below `b` to above it on the latest bar. */
+export function crossOver(first, second) {
+    requireNumericHandle('crossOver', 'first', first);
+    requireNumericHandle('crossOver', 'second', second);
+    return (first.previous !== null &&
+        second.previous !== null &&
+        first.value !== null &&
+        second.value !== null &&
+        first.previous <= second.previous &&
+        first.value > second.value);
+}
+/** True when series `a` crosses from at-or-above `b` to below it on the latest bar. */
+export function crossUnder(first, second) {
+    requireNumericHandle('crossUnder', 'first', first);
+    requireNumericHandle('crossUnder', 'second', second);
+    return (first.previous !== null &&
+        second.previous !== null &&
+        first.value !== null &&
+        second.value !== null &&
+        first.previous >= second.previous &&
+        first.value < second.value);
+}
+/** EXACT {@link EventDrivenOptions} fields (Law 12) — unknown keys are rejected, never ignored. */
+const EVENT_DRIVEN_KEYS = [
+    'data',
+    'broker',
+    'strategy',
+    'corporateActions',
+    'periodsPerYear',
+    'riskFreeRate',
+    'universe',
+];
+/** Run an event-driven backtest. */
+export function eventDriven(options) {
+    const functionName = 'eventDriven';
+    requireBarData(options, functionName, '{ data: Bar[], strategy, broker, periodsPerYear?, … }');
+    ensureKnownKeys(functionName, 'options', options, EVENT_DRIVEN_KEYS);
+    // Guard the function/object options at the boundary: a missing `strategy` used to surface as a raw
+    // "options.strategy is not a function" TypeError, and a missing `broker` as a property-read crash
+    // inside the SimulatedBroker constructor. Teach the field and a minimal working call instead (dx §1.1).
+    if (typeof options.strategy !== 'function') {
+        throw missingFieldError(functionName, 'strategy', "eventDriven({ data, broker: brokers.simulated({ cash: 100_000 }), strategy(context) { context.onBar('SPY', () => context.buy('SPY')) } })");
+    }
+    if (options.broker === null || typeof options.broker !== 'object') {
+        throw missingFieldError(functionName, 'broker', 'eventDriven({ data, broker: brokers.simulated({ cash: 100_000 }), strategy })');
+    }
+    // These two ran AFTER the simulation loop for one release: `corporateActions: 42` crashed
+    // mid-loop with a raw `.get is not a function` while the teaching guard waited at the tail.
+    // Validation happens before the first bar, like every other option here.
+    if (options.corporateActions !== undefined && !(options.corporateActions instanceof Map)) {
+        throw new InputError(`eventDriven: corporateActions must be a Map keyed \`symbol@timestampMs\` when provided. Received ${options.corporateActions === null ? 'null' : typeof options.corporateActions}.`, { code: ErrorCode.InputWrongType, context: { field: 'corporateActions' } });
+    }
+    if (options.universe !== undefined &&
+        options.universe !== 'point-in-time' &&
+        options.universe !== 'current') {
+        throw new InputError(`eventDriven: universe must be 'point-in-time' | 'current' when provided. Received ${options.universe === null ? 'null' : JSON.stringify(options.universe)}.`, { code: ErrorCode.InputInvalidEnum, context: { field: 'universe' } });
+    }
+    if (options.data.length < 2) {
+        throw new InputError(`${functionName}: need ≥ 2 bars, got ${options.data.length}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { bars: options.data.length },
+        });
+    }
+    const broker = options.broker instanceof SimulatedBroker
+        ? options.broker
+        : new SimulatedBroker(options.broker);
+    if (options['periodsPerYear'] !== undefined &&
+        (typeof options['periodsPerYear'] !== 'number' ||
+            !Number.isFinite(options['periodsPerYear']))) {
+        throw new InputError(`eventDriven: periodsPerYear must be a finite number when provided. Received ${options['periodsPerYear'] === null ? 'null' : typeof options['periodsPerYear']}.`, { code: ErrorCode.InputWrongType, context: { field: 'periodsPerYear' } });
+    }
+    const periodsPerYear = options.periodsPerYear ?? 252;
+    const initialEquity = broker.cash;
+    const handlers = new Map();
+    const barsHandlers = [];
+    const indicators = [];
+    const marks = new Map();
+    let currentBar = null;
+    const fieldExtractor = (field) => typeof field === 'function' ? field : (bar) => bar[field];
+    const submitSized = (symbol, side, opts2) => {
+        const extras = {
+            ...(opts2.type !== undefined ? { type: opts2.type } : {}),
+            ...(opts2.limitPrice !== undefined ? { limitPrice: opts2.limitPrice } : {}),
+            ...(opts2.stopPrice !== undefined ? { stopPrice: opts2.stopPrice } : {}),
+            ...(opts2.timeInForce !== undefined ? { timeInForce: opts2.timeInForce } : {}),
+            ...(opts2.takeProfit !== undefined ? { takeProfit: opts2.takeProfit } : {}),
+            ...(opts2.stopLoss !== undefined ? { stopLoss: opts2.stopLoss } : {}),
+        };
+        // Explicit share count (must be a positive finite number — never silently no-op or reverse).
+        if (opts2.quantity !== undefined) {
+            ensurePositive(opts2.quantity, 'quantity', `${functionName}.${side}`);
+            return broker.submit({ symbol, side, quantity: opts2.quantity, ...extras });
+        }
+        // Incremental notional (sized to shares at fill).
+        if (opts2.value !== undefined) {
+            ensurePositive(opts2.value, 'value', `${functionName}.${side}`);
+            return broker.submit({ symbol, side, notional: opts2.value, ...extras });
+        }
+        // Target allocation: trade the cash delta to reach `percent`·equity exposure (signed by side).
+        if (opts2.percent !== undefined) {
+            if (!(opts2.percent >= 0) || !Number.isFinite(opts2.percent)) {
+                // A negative percent would silently reverse direction (a `buy` becoming a short); reject it.
+                throw new InputError(`${functionName}.${side}: percent must be a finite number ≥ 0, got ${opts2.percent}.`, { code: ErrorCode.InputOutOfRange, context: { percent: opts2.percent } });
+            }
+            // Price the SIZED symbol with ITS OWN latest mark, never `currentBar`. Inside `context.onBars`
+            // (and inside any symbol's handler that trades a DIFFERENT symbol) `currentBar` is whichever
+            // symbol's bar the engine happened to process last, so valuing the held position at
+            // `currentBar.close` marked symbol A at symbol B's price — a silent mis-size that grew with the
+            // price gap between the two names. `marks` is the engine's per-symbol mark map (the same one
+            // `broker.equity` values the book with), so the target and the current value are now quoted in
+            // one consistent set of prices. Inside `onBar(symbol)` this is identical to the old behaviour:
+            // the engine writes `marks[symbol] = bar.close` immediately before calling that handler.
+            const position = broker.position(symbol);
+            const mark = marks.get(symbol);
+            if (mark === undefined && Math.abs(position.quantity) > 1e-12) {
+                // A held position with no mark cannot be valued — sizing off another symbol's price is
+                // exactly the defect above, so refuse rather than fabricate a target.
+                throw new InputError(`${functionName}.${side}: cannot size '${symbol}' by percent — no bar has priced it yet, but a position of ${position.quantity} is open.`, { code: ErrorCode.InputMissingField, context: { symbol, quantity: position.quantity } });
+            }
+            const price = mark ?? currentBar.close;
+            const targetValue = signOf(side) * opts2.percent * broker.equity(marks);
+            const currentValue = position.quantity * price;
+            const delta = targetValue - currentValue;
+            if (Math.abs(delta) < 1e-9)
+                return '';
+            return broker.submit({
+                symbol,
+                side: sideOf(delta),
+                notional: Math.abs(delta),
+                ...extras,
+            });
+        }
+        throw new InputError(`${functionName}: context.${side} requires one of quantity, value, or percent.`, {
+            code: ErrorCode.InputMissingField,
+            context: { symbol },
+        });
+    };
+    const context = {
+        get bar() {
+            return currentBar;
+        },
+        onBar(symbol, handler) {
+            if (handlers.has(symbol)) {
+                throw new InputError(`${functionName}: onBar('${symbol}') was already registered — one handler per symbol (register cross-sectional logic via context.onBars).`, { code: ErrorCode.BacktestDuplicateHandler, context: { symbol } });
+            }
+            handlers.set(symbol, handler);
+        },
+        onBars(handler) {
+            barsHandlers.push(handler);
+        },
+        indicator(symbol, stream, field) {
+            const handle = { value: null, previous: null };
+            indicators.push({
+                symbol,
+                stream: stream,
+                extract: fieldExtractor(field),
+                handle,
+            });
+            return handle;
+        },
+        buy(symbol, opts2 = { percent: 1 }) {
+            return submitSized(symbol, 'buy', opts2);
+        },
+        sell(symbol, opts2 = { percent: 1 }) {
+            return submitSized(symbol, 'sell', opts2);
+        },
+        close(symbol) {
+            const pos = broker.position(symbol);
+            if (Math.abs(pos.quantity) > 1e-12) {
+                broker.submit({
+                    symbol,
+                    side: sideOf(-pos.quantity), // flatten: the opposite of the held sign
+                    quantity: Math.abs(pos.quantity),
+                });
+            }
+        },
+        cancel(id) {
+            broker.cancel(id);
+        },
+        position(symbol) {
+            return broker.position(symbol);
+        },
+        registerOption(symbol, specification) {
+            broker.registerOption(symbol, specification);
+        },
+        exercise(symbol, quantity) {
+            broker.exerciseOption({
+                symbol,
+                quantity,
+                timestampMs: currentBar.timestampMs,
+                underlierMarks: marks,
+            });
+        },
+        get cash() {
+            return broker.cash;
+        },
+        get equity() {
+            return broker.equity(marks);
+        },
+    };
+    options.strategy(context);
+    // Chronological merge (stable on ties, preserving each symbol's input order).
+    const sorted = options.data
+        .map((b, i) => ({ b, i }))
+        .sort((x, y) => x.b.timestampMs - y.b.timestampMs || x.i - y.i);
+    const equityCurve = [initialEquity];
+    const timestamps = [];
+    let curTs = null;
+    const fireOnBars = () => {
+        for (const h of barsHandlers)
+            h();
+    };
+    for (const { b } of sorted) {
+        if (curTs !== null && b.timestampMs !== curTs) {
+            // The just-completed timestamp's per-symbol handlers have all run — fire the portfolio-level
+            // onBars hooks once, then settle any options expiring at that timestamp (using its marks).
+            fireOnBars();
+            broker.settleExpiries(curTs, marks);
+            equityCurve.push(broker.equity(marks));
+            timestamps.push(curTs);
+        }
+        curTs = b.timestampMs;
+        const action = options.corporateActions?.get(`${b.symbol}@${b.timestampMs}`);
+        broker.processBar(b, action);
+        marks.set(b.symbol, b.close);
+        currentBar = b;
+        for (const ind of indicators) {
+            if (ind.symbol === b.symbol) {
+                ind.handle.previous = ind.handle.value;
+                ind.handle.value = ind.stream.next(ind.extract(b));
+            }
+        }
+        handlers.get(b.symbol)?.();
+    }
+    if (curTs !== null) {
+        fireOnBars(); // portfolio-level hooks for the final timestamp
+        broker.settleExpiries(curTs, marks); // settle anything expiring at the final timestamp
+        equityCurve.push(broker.equity(marks));
+        timestamps.push(curTs);
+    }
+    const universe = options.universe ?? 'point-in-time';
+    const warnings = [...checkDataAlignment(options.data), ...broker.warnings];
+    if (universe === 'current') {
+        warnings.push({
+            code: WarningCode.ResearchSurvivorshipBias,
+            message: 'Universe is `current` (delisted names excluded); results are likely survivorship-biased.',
+            severity: 'warn',
+            context: { universe },
+        });
+    }
+    // Turnover is a CASH ratio, so each fill must be valued at its contract multiplier: a registered
+    // option trades 100 underlier shares per contract, and omitting that reported an option book's
+    // turnover at 1% of its true size.
+    const tradedNotional = broker.trades.reduce((s, t) => s + tradeNotional(t), 0);
+    const averageEquity = equityCurve.reduce((s, e) => s + e, 0) / equityCurve.length;
+    const brokerPolicies = broker.policies();
+    const assumptions = {
+        conventionsVersion: CONVENTIONS_VERSION,
+        initialCapital: initialEquity,
+        fill: 'next-bar-open / intrabar-trigger',
+        cost: brokerPolicies.cost,
+        slippage: brokerPolicies.slippage,
+        cashSettlement: 'immediate',
+        corporateAction: options.corporateActions ? 'dividends-and-splits' : 'none',
+        calendar: 'event-driven',
+        margin: brokerPolicies.margin,
+        assignment: brokerPolicies.assignment,
+        oco: brokerPolicies.oco,
+    };
+    const diagnostics = {
+        warnings,
+        benchmarkFixtureVersion: BENCHMARK_FIXTURE_VERSION,
+    };
+    return {
+        points: toEquityPoints(equityCurve, timestamps),
+        returns: equityToReturns(equityCurve),
+        // Snapshot, not the live broker array: the result must stay stable if the broker is reused.
+        trades: [...broker.trades],
+        finalValue: equityCurve[equityCurve.length - 1],
+        turnover: averageEquity > 0 ? tradedNotional / averageEquity : 0,
+        performance: analyze({ equity: equityCurve }, {
+            periodsPerYear,
+            ...(options.riskFreeRate !== undefined ? { riskFreeRate: options.riskFreeRate } : {}),
+        }),
+        assumptions,
+        diagnostics,
+        ...(broker.settlements.length > 0 ? { settlements: [...broker.settlements] } : {}),
+    };
+}
+//# sourceMappingURL=event-driven.js.map

package/modules/backtest/dist/event-driven.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-driven.js","sourceRoot":"","sources":["../src/event-driven.ts"],"names":[],"mappings":"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"}

package/modules/backtest/dist/execution/conformance.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The fill-model conformance suite (Stage 4.6, FC8 Decision 7): what a caller-supplied model must
+ * satisfy before an engine will trust it. Pure and deterministic; the same decision twice for the
+ * same inputs; never a price outside the observation's range; never more than the order asked;
+ * finite, JSON-safe decisions; inputs untouched. The built-in models pass it; a custom one that
+ * does not is refused with `backtest.adapter_nonconformant` naming the check that failed.
+ */
+import type { FillContext, FillModel, MarketObservation, OrderIntent } from './types.js';
+export interface FillModelFixture {
+    order: OrderIntent;
+    observation: MarketObservation;
+    context: FillContext;
+}
+export interface AssertFillModelConformanceInput {
+    fillModel: FillModel;
+    /** Caller fixtures run beside the built-in ones for the model's observation kind. */
+    fixtures?: readonly FillModelFixture[];
+}
+export interface FillModelConformanceResult {
+    conformant: true;
+    label: string;
+    version: string;
+    observation: MarketObservation['kind'];
+    checks: string[];
+    fixturesRun: number;
+}
+/**
+ * Run the conformance suite over the built-in fixtures for the model's observation kind and any
+ * caller fixtures. Returns the checks that passed; throws `backtest.adapter_nonconformant` on the
+ * first failure, naming the check.
+ */
+export declare function assertFillModelConformance(input: AssertFillModelConformanceInput): FillModelConformanceResult;
+//# sourceMappingURL=conformance.d.ts.map

package/modules/backtest/dist/execution/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../../src/execution/conformance.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH,OAAO,KAAK,EACV,WAAW,EAEX,SAAS,EACT,iBAAiB,EACjB,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,WAAW,CAAC;IACnB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,+BAA+B;IAC9C,SAAS,EAAE,SAAS,CAAC;IACrB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,IAAI,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAoJD;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,+BAA+B,GACrC,0BAA0B,CAkJ5B"}

package/modules/backtest/dist/execution/conformance.js

@@ -0,0 +1,269 @@
+/**
+ * The fill-model conformance suite (Stage 4.6, FC8 Decision 7): what a caller-supplied model must
+ * satisfy before an engine will trust it. Pure and deterministic; the same decision twice for the
+ * same inputs; never a price outside the observation's range; never more than the order asked;
+ * finite, JSON-safe decisions; inputs untouched. The built-in models pass it; a custom one that
+ * does not is refused with `backtest.adapter_nonconformant` naming the check that failed.
+ */
+import { ErrorCode, InputError, ensureKnownKeys, requireArgumentObject } from '../../../core/dist/index.js';
+import { canonicalJsonOf } from '../../../core/dist/artifacts/index.js';
+import { hasOwn, requireFillContext, requireFillModel, requireMarketObservation, requireOrderIntent, } from './validate.js';
+const T0 = Date.UTC(2026, 0, 5, 14, 30);
+/** A deep copy of plain JSON data (the only kind these boundaries accept); typed, lib-free. */
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function baseContext() {
+    return {
+        asOf: T0,
+        partialFills: 'allow',
+        staleQuotes: { maximumAgeMs: null, behavior: 'fill-at-last' },
+        lockedCrossed: 'fill-at-mid',
+        queue: { model: 'depth-approximation' },
+    };
+}
+function order(overrides) {
+    return {
+        orderId: 'o-1',
+        instrumentId: 'XYZ',
+        side: 'buy',
+        quantity: 100,
+        type: 'market',
+        submittedTimestampMs: T0 - 60_000,
+        ...overrides,
+    };
+}
+/** The built-in fixtures for each observation kind — one per order type and side. */
+function builtInFixtures(kind) {
+    const context = baseContext();
+    const orders = [
+        order({ type: 'market' }),
+        order({ orderId: 'o-2', side: 'sell', type: 'market' }),
+        order({ orderId: 'o-3', type: 'limit', limitPrice: 99.5 }),
+        order({ orderId: 'o-4', side: 'sell', type: 'limit', limitPrice: 100.5 }),
+        order({ orderId: 'o-5', type: 'stop', stopPrice: 100.5 }),
+        order({ orderId: 'o-6', side: 'sell', type: 'stop', stopPrice: 99.5 }),
+        order({ orderId: 'o-7', type: 'stop-limit', stopPrice: 100.5, limitPrice: 101 }),
+        order({ orderId: 'o-8', type: 'market-on-open' }),
+        order({ orderId: 'o-9', type: 'market-on-close' }),
+        order({ orderId: 'o-10', quantity: 1_000_000, type: 'market' }),
+    ];
+    let observation;
+    switch (kind) {
+        case 'bar':
+            observation = {
+                kind: 'bar',
+                bar: {
+                    symbol: 'XYZ',
+                    timestampMs: T0,
+                    open: 100,
+                    high: 101,
+                    low: 99,
+                    close: 100.5,
+                    volume: 10_000,
+                },
+            };
+            break;
+        case 'quote':
+            observation = {
+                kind: 'quote',
+                quote: {
+                    symbol: 'XYZ',
+                    timestampMs: T0,
+                    bid: 99.9,
+                    ask: 100.1,
+                    bidSize: 500,
+                    askSize: 400,
+                },
+            };
+            break;
+        case 'trade':
+            observation = {
+                kind: 'trade',
+                trade: { symbol: 'XYZ', timestampMs: T0, price: 100, size: 300 },
+            };
+            break;
+        case 'order-book':
+            observation = {
+                kind: 'order-book',
+                book: {
+                    symbol: 'XYZ',
+                    timestampMs: T0,
+                    bids: [
+                        { price: 99.9, size: 200 },
+                        { price: 99.8, size: 300 },
+                    ],
+                    asks: [
+                        { price: 100.1, size: 150 },
+                        { price: 100.2, size: 250 },
+                    ],
+                },
+            };
+            break;
+    }
+    return orders.map((o) => ({
+        order: o,
+        observation,
+        context: { ...context, participation: 0.5 },
+    }));
+}
+function observationRange(observation) {
+    switch (observation.kind) {
+        case 'bar':
+            return { low: observation.bar.low, high: observation.bar.high };
+        case 'quote':
+            return {
+                low: Math.min(observation.quote.bid, observation.quote.ask),
+                high: Math.max(observation.quote.bid, observation.quote.ask),
+            };
+        case 'trade':
+            return { low: observation.trade.price, high: observation.trade.price };
+        case 'order-book': {
+            const prices = [...observation.book.bids, ...observation.book.asks].map((level) => level.price);
+            if (prices.length === 0)
+                return null;
+            return { low: Math.min(...prices), high: Math.max(...prices) };
+        }
+    }
+}
+function isJsonSafeFinite(value) {
+    if (value === null)
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (Array.isArray(value))
+        return value.every(isJsonSafeFinite);
+    if (typeof value === 'object') {
+        return (Object.getPrototypeOf(value) === Object.prototype &&
+            Object.values(value).every(isJsonSafeFinite));
+    }
+    return false;
+}
+function fail(check, label, detail) {
+    throw new InputError(`assertFillModelConformance: fill model '${label}' failed the check "${check}" — ${detail}. A fill model must be pure, deterministic, fill inside the observation it read, never exceed the order, and return a finite JSON-safe decision.`, { code: ErrorCode.BacktestAdapterNonconformant, context: { check, fillModel: label } });
+}
+/**
+ * Run the conformance suite over the built-in fixtures for the model's observation kind and any
+ * caller fixtures. Returns the checks that passed; throws `backtest.adapter_nonconformant` on the
+ * first failure, naming the check.
+ */
+export function assertFillModelConformance(input) {
+    const functionName = 'assertFillModelConformance';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, ['fillModel', 'fixtures']);
+    let fillModel;
+    try {
+        requireFillModel(functionName, 'input.fillModel', input.fillModel);
+        fillModel = input.fillModel;
+    }
+    catch (error) {
+        // The suite's own verdict for a malformed model: nonconformant, naming what is missing.
+        fail('model-shape', String(input.fillModel?.label ?? input.fillModel), error instanceof Error ? error.message : String(error));
+    }
+    const label = fillModel.label;
+    const callerFixtures = [];
+    if (hasOwn(input, 'fixtures')) {
+        if (!Array.isArray(input.fixtures)) {
+            throw new InputError(`${functionName}: input.fixtures must be an array of { order, observation, context } when given (omit it to run the built-in fixtures only). Received ${input.fixtures === null ? 'null' : typeof input.fixtures}.`, { code: ErrorCode.InputWrongType, context: { field: 'fixtures' } });
+        }
+        input.fixtures.forEach((fixture, index) => {
+            const path = `input.fixtures[${index}]`;
+            requireArgumentObject(functionName, path, fixture);
+            ensureKnownKeys(functionName, path, fixture, ['order', 'observation', 'context']);
+            requireOrderIntent(functionName, `${path}.order`, fixture.order);
+            requireMarketObservation(functionName, `${path}.observation`, fixture.observation);
+            requireFillContext(functionName, `${path}.context`, fixture.context);
+            callerFixtures.push(fixture);
+        });
+    }
+    const fixtures = [...builtInFixtures(fillModel.observation), ...callerFixtures];
+    const checks = new Set();
+    fixtures.forEach((fixture, index) => {
+        // The model receives the fixture's OWN objects so a mutation is visible afterwards; the second
+        // call receives clones so a model that keys on identity cannot pass by accident.
+        const before = canonicalJsonOf({
+            order: fixture.order,
+            observation: fixture.observation,
+            context: fixture.context,
+        });
+        let decision;
+        let again;
+        try {
+            decision = fillModel.fill({
+                order: fixture.order,
+                observation: fixture.observation,
+                context: fixture.context,
+            });
+            again = fillModel.fill(cloneJson({
+                order: fixture.order,
+                observation: fixture.observation,
+                context: fixture.context,
+            }));
+        }
+        catch (error) {
+            if (error instanceof InputError && error.code === ErrorCode.BacktestStaleQuote) {
+                // A refusal the policy asked for is conformant behaviour, not a defect.
+                checks.add('stale-quote-refusal-is-typed');
+                return;
+            }
+            fail('no-throw', label, `fixture ${index} threw ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (canonicalJsonOf({
+            order: fixture.order,
+            observation: fixture.observation,
+            context: fixture.context,
+        }) !== before) {
+            fail('immutability', label, `fixture ${index}: the model mutated its inputs`);
+        }
+        checks.add('immutability');
+        if (!isJsonSafeFinite(decision))
+            fail('json-safe-finite', label, `fixture ${index}: the decision is not finite JSON-safe data`);
+        checks.add('json-safe-finite');
+        if (canonicalJsonOf(decision) !== canonicalJsonOf(again))
+            fail('determinism', label, `fixture ${index}: two calls disagree`);
+        checks.add('determinism');
+        if (decision.outcome !== 'filled' && decision.outcome !== 'unfilled') {
+            fail('closed-outcome', label, `fixture ${index}: outcome must be 'filled' | 'unfilled'`);
+        }
+        checks.add('closed-outcome');
+        if (decision.outcome === 'filled') {
+            if (!(decision.quantity > 0) || decision.quantity > fixture.order.quantity + 1e-12) {
+                fail('quantity-within-order', label, `fixture ${index}: filled ${decision.quantity} of ${fixture.order.quantity}`);
+            }
+            checks.add('quantity-within-order');
+            if (decision.partial !== decision.quantity < fixture.order.quantity - 1e-12) {
+                fail('partial-flag', label, `fixture ${index}: partial must be true exactly when the fill is short of the order`);
+            }
+            checks.add('partial-flag');
+            const range = observationRange(fixture.observation);
+            if (range !== null && decision.clampedToPriceLimit !== true) {
+                if (decision.pricePerUnit < range.low - 1e-12 ||
+                    decision.pricePerUnit > range.high + 1e-12) {
+                    fail('price-within-observation', label, `fixture ${index}: ${decision.pricePerUnit} outside [${range.low}, ${range.high}]`);
+                }
+            }
+            checks.add('price-within-observation');
+            if (typeof decision.reference !== 'string' || decision.reference.length === 0) {
+                fail('reference-named', label, `fixture ${index}: a fill names the price it referenced`);
+            }
+            checks.add('reference-named');
+        }
+        else {
+            if (typeof decision.reason !== 'string' || decision.reason.length === 0) {
+                fail('unfilled-reason', label, `fixture ${index}: an unfilled decision names its reason`);
+            }
+            checks.add('unfilled-reason');
+        }
+    });
+    return {
+        conformant: true,
+        label,
+        version: fillModel.version,
+        observation: fillModel.observation,
+        checks: [...checks].sort(),
+        fixturesRun: fixtures.length,
+    };
+}
+//# sourceMappingURL=conformance.js.map