Public API / @insiderfinance/totalfinance

@insiderfinance/totalfinance/backtest

import from '@insiderfinance/totalfinance/backtest'

Every public export in this entry point, including type-only declarations. Search by name or concept.

Jump to an export (132)

AgentBenchReport · AgentTranscriptScore · AttributionReport · AttributionRow · BENCHMARK_FIXTURE_VERSION · BacktestAssumptions · BacktestResult · Bar · BarField · BenchmarkComparison · BorrowModel · BrokerConfig · CorporateAction · CostModel · CrossSectionalAssumptions · CrossSectionalAttribution · CrossSectionalBacktestGridRequest · CrossSectionalBacktestGridResult · CrossSectionalBacktestRequest · CrossSectionalBacktestResult · CrossSectionalDataset · CrossSectionalDiagnostics · CrossSectionalOutOfSampleResult · CrossSectionalPurgedFoldsRequest · CrossSectionalSignal · CrossSectionalWalkForwardRequest · EnvelopeSignal · EnvironmentAction · EnvironmentEpisode · EnvironmentEpisodeInput · EnvironmentEpisodeResult · EnvironmentObservation · EnvironmentStepResult · EquityPoint · EventDrivenOptions · ExerciseOptionInput · GridVariation · GridVariationRow · HoldingReason · HoldingRow · ImplementationRisk · Indicator · IndicatorHandle · InstrumentAdapter · InstrumentSpecification · MonteCarloResampleReport · MonteCarloResampleResult · Neutrality · OptionContractSpecification · OptionSettlement · OptionSettlementStyle · Order · OrderRequest · OrderSide · OrderStatus · OrderType · OutOfSampleAssumptions · OutOfSampleDiagnostics · OutOfSampleHygiene · OutOfSampleWindowRow · PortfolioBacktestRequest · PortfolioBacktestResult · PortfolioConstruction · PortfolioStepFrame · PortfolioStepper · PortfolioStepperRequest · Position · RebalanceFrequency · RebalanceGoal · RebalanceRow · RebalanceRule · RebalanceSchedule · ReturnStatistics · ReturnStatisticsReport · SeriesSignal · SessionSpan · ShortSideSelection · SideSelection · SignalContext · SignalRow · SimulatedBroker · SlippageModel · StrategyContext · SymbolAttribution · TearSheet · TearSheetOptions · TimeInForce · Trade · TradeOptions · TradeStatistics · TradingEnvironment · TradingEnvironmentDefinition · VectorizedOptions · WalkForwardOptions · WalkForwardResult · WalkForwardWindow · WalkForwardWindowResult · WeightContext · WeightingMethod · agentBaselines · attribution · borrow · brokers · checkDataAlignment · createPortfolioStepper · createTradingEnvironment · crossOver · crossOverSeries · crossSectionalBacktest · crossSectionalBacktestGrid · crossSectionalPurgedFolds · crossSectionalWalkForward · crossUnder · crossUnderSeries · environmentEpisode · equityToReturns · eventDriven · fees · gtSeries · latchSeries · ltSeries · monteCarloResample · portfolioBacktest · returnStatistics · runAgentBench · runEnvironmentEpisode · scoreAgentTranscript · slippage · tearSheet · toEquityPoints · vectorized · walkForward

interface

AgentBenchReport

Operational conformance and strategy quality, reported separately — no single score by design.

/** Operational conformance and strategy quality, reported separately — no single score by design. */
export interface AgentBenchReport {
    policy: string;
    episodes: AgentBenchEpisodeReport[];
    /** One recorded episode per run, in the order of `episodes`. */
    traces: AgentBenchTrace[];
    operational: {
        passes: boolean;
        failing: string[];
        lookAhead: number;
        duplicateOrders: number;
        maskViolations: number;
        limitBreaches: number;
        externalOrderAttempts: 0;
    };
    strategy: {
        meanTotalReturn: number | null;
        meanSharpe: number | null;
        meanMaxDrawdown: number | null;
        meanTurnover: number | null;
        meanCost: number | null;
        meanGrossExposure: number | null;
        violations: number;
    };
    assumptions: {
        episodes: string[];
        seeds: number[];
        runs: number;
        dimensions: string;
        leakageProbe: string;
        retrySuite: string;
    };
    diagnostics: Diagnostics;
}

Fields, parameters & returned members (44)

Name / type	Meaning & unit	Optional / default
`assumptions` `{ dimensions: string; episodes: string[]; leakageProbe: string; retrySuite: string; runs: number; seeds: number[]; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.dimensions` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.episodes` `string[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.leakageProbe` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.retrySuite` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.runs` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.seeds` `number[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics` `Diagnostics`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.autoReason` `string`	When a meta-engine (e.g. `engines.auto()`) selected a delegate, this is a one-sentence, human-readable explanation of WHY that delegate was chosen (`engine` then names the delegate). Absent when no auto-selection took place. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.converged` `boolean`	Whether an iterative procedure converged. `false` means the value is not trustworthy. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.decomposition` `Record<string, number>`	Named intermediate quantities the value decomposes into — a par spread's protection leg and risky annuity, a forward variance's near/far legs. The H-series explain paths disclose their arithmetic here so a caller can audit the ratio, not just receive it (3B.3). unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.engine` `string`	Pricing/solver engine name, e.g. `black-scholes-merton`. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.finiteDifferenceBumps` `Record<string, number>`	Finite-difference engines: the ACTUAL bump sizes used for FD Greeks (spec P2.3) — adaptive near the vol/time boundaries, so the caller can see exactly what was differenced. Keys: `spotStep`, `volatilityStep`, `timeStepYears`, `rateStep`, and — extended Greeks only — `dividendYieldStep`. Each is the actual step differenced, in the unit of the coordinate it bumps. (This doc named the retired `hS`/`hSig`/`hT`/`hR`/`hQ` keys for one release after the emit sites had moved to the semantic names, so a caller following it read `undefined`.) unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.iterations` `number`	Iteration count for iterative methods. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.method` `string`	Numerical method, e.g. `closed-form`, `brent`, `finite-difference`. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.selection` `import('@insiderfinance/totalfinance/core/pricing').SelectionReport`	The structured engine-selection report (Gate C, `@insiderfinance/totalfinance/core/pricing`): who was selected, why, and — for automatic selection — every candidate considered with its verdict. This is the machine-readable superset of `engine` + `autoReason` (which remain for compatibility); `selected.name` always agrees with `engine` when both are present. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.selection.candidates` `readonly import('@insiderfinance/totalfinance/core/pricing').SelectionCandidate[]`	Candidates an automatic selection considered; absent for explicit mode. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.selection.mode` `'explicit' \| 'automatic'`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.reason` `string`	Why the selected engine answers this request. unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.selected` `{ name: string; version?: string; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.selected.name` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.selected.version` `string`	unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.timingMs` `number`	Wall-clock timing in milliseconds, when measured. milliseconds	Optional No @default declared; consult the signature and description.
`diagnostics.warmup` `number`	Series facades: number of leading output slots that are warmup sentinels (null/NaN) while the computation seeds. Equals the input length when the indicator never emitted. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.warnings` `QuantWarning[]`	Structured warnings; always present (possibly empty). unitless by name	Required / declared member No @default declared; consult the signature and description.
`episodes` `AgentBenchEpisodeReport[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`operational` `{ duplicateOrders: number; externalOrderAttempts: 0; failing: string[]; limitBreaches: number; lookAhead: number; maskViolations: number; passes: boolean; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`operational.duplicateOrders` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`operational.externalOrderAttempts` `0`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`operational.failing` `string[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`operational.limitBreaches` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`operational.lookAhead` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`operational.maskViolations` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`operational.passes` `boolean`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`policy` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`strategy` `{ meanCost: number \| null; meanGrossExposure: number \| null; meanMaxDrawdown: number \| null; meanSharpe: number \| null; meanTotalReturn: number \| null; meanTurnover: number \| null; violations: number; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`strategy.meanCost` `number \| null`	currency amount (the field or record currency)	Required / declared member No @default declared; consult the signature and description.
`strategy.meanGrossExposure` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`strategy.meanMaxDrawdown` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`strategy.meanSharpe` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`strategy.meanTotalReturn` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`strategy.meanTurnover` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`strategy.violations` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`traces` `AgentBenchTrace[]`	One recorded episode per run, in the order of `episodes`. unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.

interface

AgentTranscriptScore

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface AgentTranscriptScore {
    operationSelection: number;
    firstAttemptValidity: number | null;
    recovery: number | null;
    argumentValidity: number | null;
    parity: boolean | null;
    refusal: boolean | null;
    traceability: number | null;
    calls: number;
    bytes: number;
    withinBudget: boolean | null;
    passes: boolean;
    assumptions: {
        deterministic: true;
        scoring: string;
    };
    diagnostics: Diagnostics;
}

Fields, parameters & returned members (32)

Name / type	Meaning & unit	Optional / default
`argumentValidity` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions` `{ deterministic: true; scoring: string; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.deterministic` `true`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.scoring` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`bytes` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`calls` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics` `Diagnostics`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.autoReason` `string`	When a meta-engine (e.g. `engines.auto()`) selected a delegate, this is a one-sentence, human-readable explanation of WHY that delegate was chosen (`engine` then names the delegate). Absent when no auto-selection took place. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.converged` `boolean`	Whether an iterative procedure converged. `false` means the value is not trustworthy. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.decomposition` `Record<string, number>`	Named intermediate quantities the value decomposes into — a par spread's protection leg and risky annuity, a forward variance's near/far legs. The H-series explain paths disclose their arithmetic here so a caller can audit the ratio, not just receive it (3B.3). unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.engine` `string`	Pricing/solver engine name, e.g. `black-scholes-merton`. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.finiteDifferenceBumps` `Record<string, number>`	Finite-difference engines: the ACTUAL bump sizes used for FD Greeks (spec P2.3) — adaptive near the vol/time boundaries, so the caller can see exactly what was differenced. Keys: `spotStep`, `volatilityStep`, `timeStepYears`, `rateStep`, and — extended Greeks only — `dividendYieldStep`. Each is the actual step differenced, in the unit of the coordinate it bumps. (This doc named the retired `hS`/`hSig`/`hT`/`hR`/`hQ` keys for one release after the emit sites had moved to the semantic names, so a caller following it read `undefined`.) unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.iterations` `number`	Iteration count for iterative methods. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.method` `string`	Numerical method, e.g. `closed-form`, `brent`, `finite-difference`. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.selection` `import('@insiderfinance/totalfinance/core/pricing').SelectionReport`	The structured engine-selection report (Gate C, `@insiderfinance/totalfinance/core/pricing`): who was selected, why, and — for automatic selection — every candidate considered with its verdict. This is the machine-readable superset of `engine` + `autoReason` (which remain for compatibility); `selected.name` always agrees with `engine` when both are present. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.selection.candidates` `readonly import('@insiderfinance/totalfinance/core/pricing').SelectionCandidate[]`	Candidates an automatic selection considered; absent for explicit mode. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.selection.mode` `'explicit' \| 'automatic'`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.reason` `string`	Why the selected engine answers this request. unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.selected` `{ name: string; version?: string; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.selected.name` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.selected.version` `string`	unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.timingMs` `number`	Wall-clock timing in milliseconds, when measured. milliseconds	Optional No @default declared; consult the signature and description.
`diagnostics.warmup` `number`	Series facades: number of leading output slots that are warmup sentinels (null/NaN) while the computation seeds. Equals the input length when the indicator never emitted. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.warnings` `QuantWarning[]`	Structured warnings; always present (possibly empty). unitless by name	Required / declared member No @default declared; consult the signature and description.
`firstAttemptValidity` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`operationSelection` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`parity` `boolean \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`passes` `boolean`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`recovery` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`refusal` `boolean \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`traceability` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`withinBudget` `boolean \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

AttributionReport

{@link attribution} as a report: per-symbol rows carrying `assumptions` + `diagnostics` inline.

/** {@link attribution} as a report: per-symbol rows carrying `assumptions` + `diagnostics` inline. */
export interface AttributionReport {
    /** Realized P&L per symbol (average-cost matched), in first-trade order. */
    bySymbol: SymbolAttribution[];
    assumptions: {
        conventionsVersion: string;
        [k: string]: unknown;
    };
    diagnostics: {
        warnings: QuantWarning[];
    };
}

Fields, parameters & returned members (5)

Name / type	Meaning & unit	Optional / default
`assumptions` `{ [k: string]: unknown; conventionsVersion: string; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.conventionsVersion` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`bySymbol` `SymbolAttribution[]`	Realized P&L per symbol (average-cost matched), in first-trade order. unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics` `{ warnings: QuantWarning[]; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.warnings` `QuantWarning[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

AttributionRow

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface AttributionRow {
    rebalanceIndex: number;
    sessionDate: string;
    /** Pearson IC of the signal against the next-period return; null when unmeasurable. */
    informationCoefficient: number | null;
    rankInformationCoefficient: number | null;
    /** Long-leg minus short-leg mean next-period return of the signal's quantiles. */
    spreadReturn: number | null;
    /** Fraction of this rebalance's selection not present in the previous one. */
    selectionTurnover: number | null;
    breadth: number;
    coverage: number;
}

Fields, parameters & returned members (8)

Name / type	Meaning & unit	Optional / default
`breadth` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`coverage` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`informationCoefficient` `number \| null`	Pearson IC of the signal against the next-period return; null when unmeasurable. unitless by name	Required / declared member No @default declared; consult the signature and description.
`rankInformationCoefficient` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`rebalanceIndex` `number`	count (integer)	Required / declared member No @default declared; consult the signature and description.
`selectionTurnover` `number \| null`	Fraction of this rebalance's selection not present in the previous one. unitless by name	Required / declared member No @default declared; consult the signature and description.
`sessionDate` `string`	calendar date (YYYY-MM-DD)	Required / declared member No @default declared; consult the signature and description.
`spreadReturn` `number \| null`	Long-leg minus short-leg mean next-period return of the signal's quantiles. unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

value

BENCHMARK_FIXTURE_VERSION

Version tag of the golden benchmark fixtures the engines are validated against (spec §16.3).

export declare const BENCHMARK_FIXTURE_VERSION: '0.0.1';

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

BacktestAssumptions

The modelling assumptions a backtest makes, echoed on every result's `assumptions` slot so they are never hidden (spec §16.3 / dx §2.5). Each policy is a short, stable, machine-readable label.

/**
 * The modelling assumptions a backtest makes, echoed on every result's `assumptions` slot so they are
 * never hidden (spec §16.3 / dx §2.5). Each policy is a short, stable, machine-readable label.
 */
export interface BacktestAssumptions {
    /** Version of the library's default conventions (core `CONVENTIONS_VERSION`). */
    conventionsVersion: string;
    /** Opening capital the run started from. */
    initialCapital: number;
    /** When/at what price orders fill, e.g. `next-open`, `close`, `trigger-price`. */
    fill: string;
    /** Commission model applied, e.g. `bps(1)`, `per-share(0.005)`, `none`. */
    cost: string;
    /** Slippage model applied, e.g. `bps(2)`, `spread`, `none`. */
    slippage: string;
    /** Cash settlement assumption, e.g. `immediate` (T+0). */
    cashSettlement: string;
    /** Corporate-action handling, e.g. `dividends-as-cash`, `splits-adjusted`, `none`. */
    corporateAction: string;
    /** Rebalancing/trading calendar, e.g. `every-bar`, `monthly`, `signal-driven`. */
    calendar: string;
    /** Leverage/margin regime: `unconstrained` (no cap; unfunded fills allowed) or `maxLeverage`. */
    margin: string;
    /** American early exercise/assignment policy: `model` or `none` (WS7.4). Absent where inapplicable. */
    assignment?: string;
    /**
     * How an OCO group resolves a bar that touches BOTH legs. One bar cannot say which trigger came
     * first, and the engine's answer — the take-profit, because a bracket submits it before the
     * stop-loss and orders fill in submission order — is optimistic. It is disclosed here rather than
     * left as an undocumented mechanic (`take-profit-first-on-ambiguous-bar`). Absent for engines with
     * no order book (the vectorized loop).
     */
    oco?: string;
}

Fields, parameters & returned members (11)

Name / type	Meaning & unit	Optional / default
`assignment` `string`	American early exercise/assignment policy: `model` or `none` (WS7.4). Absent where inapplicable. unitless by name	Optional No @default declared; consult the signature and description.
`calendar` `string`	Rebalancing/trading calendar, e.g. `every-bar`, `monthly`, `signal-driven`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`cashSettlement` `string`	Cash settlement assumption, e.g. `immediate` (T+0). unitless by name	Required / declared member No @default declared; consult the signature and description.
`conventionsVersion` `string`	Version of the library's default conventions (core `CONVENTIONS_VERSION`). unitless by name	Required / declared member No @default declared; consult the signature and description.
`corporateAction` `string`	Corporate-action handling, e.g. `dividends-as-cash`, `splits-adjusted`, `none`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`cost` `string`	Commission model applied, e.g. `bps(1)`, `per-share(0.005)`, `none`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`fill` `string`	When/at what price orders fill, e.g. `next-open`, `close`, `trigger-price`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`initialCapital` `number`	Opening capital the run started from. unitless by name	Required / declared member No @default declared; consult the signature and description.
`margin` `string`	Leverage/margin regime: `unconstrained` (no cap; unfunded fills allowed) or `maxLeverage`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`oco` `string`	How an OCO group resolves a bar that touches BOTH legs. One bar cannot say which trigger came first, and the engine's answer — the take-profit, because a bracket submits it before the stop-loss and orders fill in submission order — is optimistic. It is disclosed here rather than left as an undocumented mechanic (`take-profit-first-on-ambiguous-bar`). Absent for engines with no order book (the vectorized loop). unitless by name	Optional No @default declared; consult the signature and description.
`slippage` `string`	Slippage model applied, e.g. `bps(2)`, `spread`, `none`. unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

BacktestResult

The common result shape returned by both engines.

/** The common result shape returned by both engines. */
export interface BacktestResult {
    /**
     * The equity curve as an explicit `(ts, equity)` series (length = number of bars + 1). `points[0]`
     * is the opening capital stamped at the first bar's timestamp; see {@link EquityPoint}.
     */
    points: EquityPoint[];
    /** Per-bar simple returns of the equity curve. */
    returns: number[];
    /** Every filled trade, in order. */
    trades: Trade[];
    /** Final portfolio value. */
    finalValue: number;
    /** Sum of |traded notional| ÷ average equity — a turnover proxy. */
    turnover: number;
    /** Performance metrics of the equity curve (`@insiderfinance/totalfinance/performance`). */
    performance: PerformanceSummary;
    /** The modelling assumptions this run made — capital, fills, costs, calendar, margin (dx §2.5). */
    assumptions: BacktestAssumptions;
    /** Implementation-risk diagnostics: warnings + benchmark fixture version (spec §16.3). */
    diagnostics: ImplementationRisk;
    /** Option positions settled at expiry (exercise / assignment / worthless), if any. */
    settlements?: OptionSettlement[];
}

Fields, parameters & returned members (66)

Name / type	Meaning & unit	Optional / default
`assumptions` `BacktestAssumptions`	The modelling assumptions this run made — capital, fills, costs, calendar, margin (dx §2.5). unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.assignment` `string`	American early exercise/assignment policy: `model` or `none` (WS7.4). Absent where inapplicable. unitless by name	Optional No @default declared; consult the signature and description.
`assumptions.calendar` `string`	Rebalancing/trading calendar, e.g. `every-bar`, `monthly`, `signal-driven`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.cashSettlement` `string`	Cash settlement assumption, e.g. `immediate` (T+0). unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.conventionsVersion` `string`	Version of the library's default conventions (core `CONVENTIONS_VERSION`). unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.corporateAction` `string`	Corporate-action handling, e.g. `dividends-as-cash`, `splits-adjusted`, `none`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.cost` `string`	Commission model applied, e.g. `bps(1)`, `per-share(0.005)`, `none`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.fill` `string`	When/at what price orders fill, e.g. `next-open`, `close`, `trigger-price`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.initialCapital` `number`	Opening capital the run started from. unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.margin` `string`	Leverage/margin regime: `unconstrained` (no cap; unfunded fills allowed) or `maxLeverage`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.oco` `string`	How an OCO group resolves a bar that touches BOTH legs. One bar cannot say which trigger came first, and the engine's answer — the take-profit, because a bracket submits it before the stop-loss and orders fill in submission order — is optimistic. It is disclosed here rather than left as an undocumented mechanic (`take-profit-first-on-ambiguous-bar`). Absent for engines with no order book (the vectorized loop). unitless by name	Optional No @default declared; consult the signature and description.
`assumptions.slippage` `string`	Slippage model applied, e.g. `bps(2)`, `spread`, `none`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics` `ImplementationRisk`	Implementation-risk diagnostics: warnings + benchmark fixture version (spec §16.3). unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.autoReason` `string`	When a meta-engine (e.g. `engines.auto()`) selected a delegate, this is a one-sentence, human-readable explanation of WHY that delegate was chosen (`engine` then names the delegate). Absent when no auto-selection took place. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.benchmarkFixtureVersion` `string`	The benchmark fixture version this engine was validated against. unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.converged` `boolean`	Whether an iterative procedure converged. `false` means the value is not trustworthy. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.decomposition` `Record<string, number>`	Named intermediate quantities the value decomposes into — a par spread's protection leg and risky annuity, a forward variance's near/far legs. The H-series explain paths disclose their arithmetic here so a caller can audit the ratio, not just receive it (3B.3). unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.engine` `string`	Pricing/solver engine name, e.g. `black-scholes-merton`. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.finiteDifferenceBumps` `Record<string, number>`	Finite-difference engines: the ACTUAL bump sizes used for FD Greeks (spec P2.3) — adaptive near the vol/time boundaries, so the caller can see exactly what was differenced. Keys: `spotStep`, `volatilityStep`, `timeStepYears`, `rateStep`, and — extended Greeks only — `dividendYieldStep`. Each is the actual step differenced, in the unit of the coordinate it bumps. (This doc named the retired `hS`/`hSig`/`hT`/`hR`/`hQ` keys for one release after the emit sites had moved to the semantic names, so a caller following it read `undefined`.) unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.iterations` `number`	Iteration count for iterative methods. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.method` `string`	Numerical method, e.g. `closed-form`, `brent`, `finite-difference`. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.selection` `import('@insiderfinance/totalfinance/core/pricing').SelectionReport`	The structured engine-selection report (Gate C, `@insiderfinance/totalfinance/core/pricing`): who was selected, why, and — for automatic selection — every candidate considered with its verdict. This is the machine-readable superset of `engine` + `autoReason` (which remain for compatibility); `selected.name` always agrees with `engine` when both are present. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.selection.candidates` `readonly import('@insiderfinance/totalfinance/core/pricing').SelectionCandidate[]`	Candidates an automatic selection considered; absent for explicit mode. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.selection.mode` `'explicit' \| 'automatic'`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.reason` `string`	Why the selected engine answers this request. unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.selected` `{ name: string; version?: string; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.selected.name` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.selected.version` `string`	unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.timingMs` `number`	Wall-clock timing in milliseconds, when measured. milliseconds	Optional No @default declared; consult the signature and description.
`diagnostics.warmup` `number`	Series facades: number of leading output slots that are warmup sentinels (null/NaN) while the computation seeds. Equals the input length when the indicator never emitted. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.warnings` `import('@insiderfinance/totalfinance/core').QuantWarning[]`	Structured warnings; always present (possibly empty). unitless by name	Required / declared member No @default declared; consult the signature and description.
`finalValue` `number`	Final portfolio value. currency amount (the field or record currency)	Required / declared member No @default declared; consult the signature and description.
`performance` `PerformanceSummary`	Performance metrics of the equity curve (`@insiderfinance/totalfinance/performance`). unitless by name	Required / declared member No @default declared; consult the signature and description.
`performance.alpha` `number \| null`	Annualized Jensen's alpha (only when `options.benchmark` is supplied). unitless by name	Optional No @default declared; consult the signature and description.
`performance.annualizedReturn` `number \| null`	`null` when compounding overflowed (disclosed via `performance.non_finite_metric`). unitless by name	Required / declared member No @default declared; consult the signature and description.
`performance.annualizedVolatility` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`performance.assumptions` `{ benchmarkLength?: number; periodsPerYear: number; riskFreeRate: number; }`	The conventions actually applied — a serialized summary is self-interpreting (spec §7.4). unitless by name	Required / declared member No @default declared; consult the signature and description.
`performance.assumptions.benchmarkLength` `number`	Length of the benchmark return series, present only when a benchmark was supplied. count (integer)	Optional No @default declared; consult the signature and description.
`performance.assumptions.periodsPerYear` `number`	Annualization factor used for all annualized metrics. per year (count)	Required / declared member No @default declared; consult the signature and description.
`performance.assumptions.riskFreeRate` `number`	Per-period risk-free rate used for Sharpe/Sortino/alpha/Treynor (0 when unspecified). decimal rate (0.05 = 5%)	Required / declared member No @default declared; consult the signature and description.
`performance.beta` `number \| null`	Beta to the benchmark (only when `options.benchmark` is supplied). unitless by name	Optional No @default declared; consult the signature and description.
`performance.calmar` `number \| null`	`null` when the metric is undefined for this input (disclosed via warnings). unitless by name	Required / declared member No @default declared; consult the signature and description.
`performance.drawdown` `import('@insiderfinance/totalfinance/performance').DrawdownResult`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`performance.drawdown.longestDurationPeriods` `number`	Longest underwater stretch, in periods. periods	Required / declared member No @default declared; consult the signature and description.
`performance.drawdown.maxDrawdown` `number`	Maximum drawdown as a positive fraction (0.2 = a 20% peak-to-trough decline). unitless by name	Required / declared member No @default declared; consult the signature and description.
`performance.drawdown.peakIndex` `number`	Index of the peak preceding the worst drawdown. count (integer)	Required / declared member No @default declared; consult the signature and description.
`performance.drawdown.recoveryIndex` `number`	Index at which equity first regained the pre-drawdown peak after the worst trough (WS3.3c). Absent when the curve never recovered by the end of the series (still underwater). count (integer)	Optional No @default declared; consult the signature and description.
`performance.drawdown.troughIndex` `number`	Index of the trough of the worst drawdown. count (integer)	Required / declared member No @default declared; consult the signature and description.
`performance.expectancy` `number \| null`	Mean per-period return (expectancy); `null` on an empty series or overflow (disclosed). unitless by name	Required / declared member No @default declared; consult the signature and description.
`performance.hitRate` `number \| null`	`null` when the metric is undefined for this input (disclosed via warnings). decimal rate (0.05 = 5%)	Required / declared member No @default declared; consult the signature and description.
`performance.informationRatio` `number \| null`	Information ratio (only when `options.benchmark` is supplied). decimal fraction / multiple	Optional No @default declared; consult the signature and description.
`performance.maxDrawdown` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`performance.omega` `number \| null`	`null` when the metric is undefined for this input (disclosed via warnings). unitless by name	Required / declared member No @default declared; consult the signature and description.
`performance.periods` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`performance.profitFactor` `number \| null`	`null` when the metric is undefined for this input (disclosed via warnings). decimal fraction / multiple	Required / declared member No @default declared; consult the signature and description.
`performance.sharpe` `number \| null`	`null` when the metric is undefined for this input (disclosed via warnings). unitless by name	Required / declared member No @default declared; consult the signature and description.
`performance.sortino` `number \| null`	`null` when the metric is undefined for this input (disclosed via warnings). unitless by name	Required / declared member No @default declared; consult the signature and description.
`performance.totalReturn` `number \| null`	`null` when compounding overflowed (disclosed via `performance.non_finite_metric`). unitless by name	Required / declared member No @default declared; consult the signature and description.
`performance.trackingError` `number \| null`	Annualized tracking error (only when `options.benchmark` is supplied). unitless by name	Optional No @default declared; consult the signature and description.
`performance.treynor` `number \| null`	Treynor ratio (only when `options.benchmark` is supplied). unitless by name	Optional No @default declared; consult the signature and description.
`performance.warnings` `import('@insiderfinance/totalfinance/core').QuantWarning[]`	Diagnostics — e.g. `performance.suspicious_equity_input` when an equity curve looks like returns. unitless by name	Required / declared member No @default declared; consult the signature and description.
`points` `EquityPoint[]`	The equity curve as an explicit `(ts, equity)` series (length = number of bars + 1). `points[0]` is the opening capital stamped at the first bar's timestamp; see {@link EquityPoint}. unitless by name	Required / declared member No @default declared; consult the signature and description.
`returns` `number[]`	Per-bar simple returns of the equity curve. unitless by name	Required / declared member No @default declared; consult the signature and description.
`settlements` `OptionSettlement[]`	Option positions settled at expiry (exercise / assignment / worthless), if any. unitless by name	Optional No @default declared; consult the signature and description.
`trades` `Trade[]`	Every filled trade, in order. unitless by name	Required / declared member No @default declared; consult the signature and description.
`turnover` `number`	Sum of \|traded notional\| ÷ average equity — a turnover proxy. unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

Bar

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface Bar {
    symbol: SymbolId;
    timestampMs: EpochMs;
    open: number;
    high: number;
    low: number;
    close: number;
    volume?: number;
    vwap?: number;
    adjusted?: boolean;
}

Fields, parameters & returned members (9)

Name / type	Meaning & unit	Optional / default
`adjusted` `boolean`	unitless by name	Optional No @default declared; consult the signature and description.
`close` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`high` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`low` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`open` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`symbol` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`timestampMs` `number`	milliseconds	Required / declared member No @default declared; consult the signature and description.
`volume` `number`	unitless by name	Optional No @default declared; consult the signature and description.
`vwap` `number`	unitless by name	Optional No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

type

BarField

Field of a bar to feed an indicator, or a custom extractor.

/** Field of a bar to feed an indicator, or a custom extractor. */
export type BarField = 'open' | 'high' | 'low' | 'close' | 'volume';

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

BenchmarkComparison

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface BenchmarkComparison {
    instrumentId: string;
    /** The benchmark's per-session simple returns aligned to the run's sessions. */
    returns: number[];
    activeReturn: number | null;
    trackingError: number | null;
    informationRatio: number | null;
    beta: number | null;
    alpha: number | null;
}

Fields, parameters & returned members (7)

Name / type	Meaning & unit	Optional / default
`activeReturn` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`alpha` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`beta` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`informationRatio` `number \| null`	decimal fraction / multiple	Required / declared member No @default declared; consult the signature and description.
`instrumentId` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`returns` `number[]`	The benchmark's per-session simple returns aligned to the run's sessions. unitless by name	Required / declared member No @default declared; consult the signature and description.
`trackingError` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

BorrowModel

A borrow-fee model for short positions: an annualized financing rate on the short market value.

/** A borrow-fee model for short positions: an annualized financing rate on the short market value. */
export interface BorrowModel {
    readonly label: string;
    /** Annualized borrow rate (decimal, e.g. `0.005` = 50 bps/yr). */
    readonly annualRate: number;
}

Fields, parameters & returned members (2)

Name / type	Meaning & unit	Optional / default
`annualRate` `number`	Annualized borrow rate (decimal, e.g. `0.005` = 50 bps/yr). decimal rate (0.05 = 5%)	Required / declared member No @default declared; consult the signature and description.
`label` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

BrokerConfig

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface BrokerConfig {
    /** Opening cash. */
    cash: number;
    commission?: CostModel;
    slippage?: SlippageModel;
    borrow?: BorrowModel;
    /** Bars per year, for borrow accrual (default 252). */
    periodsPerYear?: number;
    /** Max gross leverage `Σ|positionNotional| / equity` allowed at fill (default `Infinity`). */
    maxLeverage?: number;
    /** Disallow short positions (default `false`). */
    noShort?: boolean;
    /** Cap a single bar's fill to this fraction of bar volume (partial fills); default `Infinity`. */
    maxVolumeParticipation?: number;
    /**
     * American early exercise/assignment policy (WS7.4). `'none'` (default) settles options only at
     * expiry — every European-style golden is byte-identical. `'model'` options in to modeling early
     * assignment of American short options at ex-dividend dates (short calls) and deep-ITM thresholds
     * (short puts), plus manual `exerciseOption`/`context.exercise` for American longs.
     */
    assignment?: 'model' | 'none';
    /**
     * Short-put early-assignment buffer as a FRACTION of strike (default `0.02`): a short put is
     * assigned early when the interest CARRY benefit of exercising now exceeds the remaining extrinsic
     * (time value) by more than `threshold·strike`. Only used when `assignment: 'model'`.
     */
    assignmentThreshold?: number;
    /**
     * Continuously-compounded risk-free rate (decimal, default `0`) used ONLY for the short-put
     * early-assignment carry economics — early put exercise is driven by the interest earned on the
     * strike over the option's remaining life. With rate `0` there is no carry incentive, so a short
     * put is never assigned early on arbitrage-free prices. Only used when `assignment: 'model'`.
     */
    riskFreeRate?: number;
}

Fields, parameters & returned members (24)

Name / type	Meaning & unit	Optional / default
`assignment` `'none' \| 'model'`	American early exercise/assignment policy (WS7.4). `'none'` (default) settles options only at expiry — every European-style golden is byte-identical. `'model'` options in to modeling early assignment of American short options at ex-dividend dates (short calls) and deep-ITM thresholds (short puts), plus manual `exerciseOption`/`context.exercise` for American longs. unitless by name	Optional No @default declared; consult the signature and description.
`assignmentThreshold` `number`	Short-put early-assignment buffer as a FRACTION of strike (default `0.02`): a short put is assigned early when the interest CARRY benefit of exercising now exceeds the remaining extrinsic (time value) by more than `threshold·strike`. Only used when `assignment: 'model'`. unitless by name	Optional No @default declared; consult the signature and description.
`borrow` `BorrowModel`	unitless by name	Optional No @default declared; consult the signature and description.
`borrow.annualRate` `number`	Annualized borrow rate (decimal, e.g. `0.005` = 50 bps/yr). decimal rate (0.05 = 5%)	Required / declared member No @default declared; consult the signature and description.
`borrow.label` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`cash` `number`	Opening cash. unitless by name	Required / declared member No @default declared; consult the signature and description.
`commission` `CostModel`	unitless by name	Optional No @default declared; consult the signature and description.
`commission.commission` `(input: import('@insiderfinance/totalfinance/backtest/costs').CommissionInput) => number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`commission.commission(input)` `import('@insiderfinance/totalfinance/backtest/costs').CommissionInput`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`commission.commission(input).price` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`commission.commission(input).quantity` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`commission.label` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`maxLeverage` `number`	Max gross leverage `Σ\|positionNotional\| / equity` allowed at fill (default `Infinity`). unitless by name	Optional No @default declared; consult the signature and description.
`maxVolumeParticipation` `number`	Cap a single bar's fill to this fraction of bar volume (partial fills); default `Infinity`. unitless by name	Optional No @default declared; consult the signature and description.
`noShort` `boolean`	Disallow short positions (default `false`). unitless by name	Optional No @default declared; consult the signature and description.
`periodsPerYear` `number`	Bars per year, for borrow accrual (default 252). per year (count)	Optional No @default declared; consult the signature and description.
`riskFreeRate` `number`	Continuously-compounded risk-free rate (decimal, default `0`) used ONLY for the short-put early-assignment carry economics — early put exercise is driven by the interest earned on the strike over the option's remaining life. With rate `0` there is no carry incentive, so a short put is never assigned early on arbitrage-free prices. Only used when `assignment: 'model'`. decimal rate (0.05 = 5%)	Optional No @default declared; consult the signature and description.
`slippage` `SlippageModel`	unitless by name	Optional No @default declared; consult the signature and description.
`slippage.fill` `(input: import('@insiderfinance/totalfinance/backtest/costs').SlippageFillInput) => number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`slippage.fill(input)` `import('@insiderfinance/totalfinance/backtest/costs').SlippageFillInput`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`slippage.fill(input).quantity` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`slippage.fill(input).referencePrice` `number`	currency amount (the field or record currency)	Required / declared member No @default declared; consult the signature and description.
`slippage.fill(input).side` `OrderSide`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`slippage.label` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

CorporateAction

A corporate action effective on a bar.

/** A corporate action effective on a bar. */
export interface CorporateAction {
    /** Cash dividend per share (long receives, short pays). */
    dividend?: number;
    /** Split ratio `R` (`2` = 2-for-1: quantities ×R, prices ÷R). */
    split?: number;
}

Fields, parameters & returned members (2)

Name / type	Meaning & unit	Optional / default
`dividend` `number`	Cash dividend per share (long receives, short pays). unitless by name	Optional No @default declared; consult the signature and description.
`split` `number`	Split ratio `R` (`2` = 2-for-1: quantities ×R, prices ÷R). unitless by name	Optional No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

CostModel

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface CostModel {
    readonly label: string;
    commission(input: CommissionInput): number;
}

Fields, parameters & returned members (5)

Name / type	Meaning & unit	Optional / default
`commission` `(input: CommissionInput) => number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`commission(input)` `CommissionInput`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`commission(input).price` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`commission(input).quantity` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`label` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

CrossSectionalAssumptions

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface CrossSectionalAssumptions {
    conventionsVersion: string;
    universeId: string;
    signal: {
        kind: 'factor-recipe';
        recipeName: string;
        recipeVersion: number;
        direction: string;
        lagTradingSessions: number;
        neutralization: string;
    } | {
        kind: 'score';
        components: number;
        missingValuePolicy: string;
    } | {
        kind: 'screen';
        orderBy: string[];
        missingValuePolicy: string;
    } | {
        kind: 'callback';
        replayable: false;
    };
    rebalanceSchedule: {
        frequency: RebalanceFrequency;
        session: 'open' | 'close';
        bufferBand: number | null;
    };
    sessionInstantConvention: string;
    pricing: string;
    portfolioConstruction: {
        method: WeightingMethod;
        long: SideSelection;
        short: ShortSideSelection | null;
        neutrality: Neutrality;
        maximumPositions: number | null;
        maximumPositionWeight: number | null;
        minimumPositionWeight: number | null;
        maximumTurnover: number | null;
        maximumParticipation: number | null;
        volatilityLookbackSessions: number;
        shortBookSizing: string;
    };
    execution: ExecutionPolicyDescription;
    costs: {
        commission: string;
        slippage: string;
    };
    initialCapital: number;
    baseCurrency: string;
    periodsPerYear: number;
    riskFreeRate: number;
    seed: number | null;
    window: {
        fromTimestampMs: EpochMs | null;
        toTimestampMs: EpochMs | null;
    };
    ledger: {
        sourceId: string;
        accountId: string;
        lotRelief: string;
    };
    replayable: boolean;
}

Fields, parameters & returned members (87)

Name / type	Meaning & unit	Optional / default
`baseCurrency` `string`	ISO-4217 currency code	Required / declared member No @default declared; consult the signature and description.
`conventionsVersion` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`costs` `{ commission: string; slippage: string; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`costs.commission` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`costs.slippage` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution` `ExecutionPolicyDescription`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.ambiguity` `import('@insiderfinance/totalfinance/backtest/execution').AmbiguityPolicy`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.costs` `{ borrow: string \| null; commission: string; latencySessions: number \| null; marketImpact: string \| null; participation: number \| null; slippage: string; spread: string \| null; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.costs.borrow` `string \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.costs.commission` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.costs.latencySessions` `number \| null`	trading sessions	Required / declared member No @default declared; consult the signature and description.
`execution.costs.marketImpact` `string \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.costs.participation` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.costs.slippage` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.costs.spread` `string \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.fill` `{ label: string; version: string; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.fill.label` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.fill.version` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.label` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.lockedCrossed` `import('@insiderfinance/totalfinance/backtest/execution').LockedCrossedPolicy`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.margin` `import('@insiderfinance/totalfinance/backtest/execution').MarginPolicy`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.margin.buyingPowerMultiplier` `number`	Gross notional an account may hold per unit of equity (1 = cash account). decimal fraction / multiple	Required / declared member No @default declared; consult the signature and description.
`execution.margin.forcedLiquidation` `import('@insiderfinance/totalfinance/backtest/execution').ForcedLiquidationPolicy`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.margin.initialMarginRate` `number`	Fraction of a new position's notional that must be equity at entry. decimal rate (0.05 = 5%)	Required / declared member No @default declared; consult the signature and description.
`execution.margin.maintenanceMarginRate` `number`	Fraction of gross notional that must remain equity after every fold. decimal rate (0.05 = 5%)	Required / declared member No @default declared; consult the signature and description.
`execution.observation` `'quote' \| 'bar' \| 'trade' \| 'order-book'`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.partialFills` `import('@insiderfinance/totalfinance/backtest/execution').PartialFillPolicy`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.queue` `import('@insiderfinance/totalfinance/backtest/execution').QueueModel`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.realism` `'simplified' \| 'declared'`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.sessions` `{ auction: 'ignore' \| 'open-close-only' \| null; halts: number; priceLimits: number; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.sessions.auction` `'ignore' \| 'open-close-only' \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.sessions.halts` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.sessions.priceLimits` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.staleQuotes` `import('@insiderfinance/totalfinance/backtest/execution').StaleQuotePolicy`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.staleQuotes.behavior` `'reject' \| 'fill-at-last'`	`reject` refuses the run (`backtest.stale_quote`); `fill-at-last` fills at the stale quote and reports it. unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.staleQuotes.maximumAgeMs` `number \| null`	A quote older than this at the decision instant is stale; `null` = never stale. milliseconds	Required / declared member No @default declared; consult the signature and description.
`execution.timeInForce` `{ default: import('@insiderfinance/totalfinance/core').TimeInForce; expireAtSessionClose: boolean; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.timeInForce.default` `import('@insiderfinance/totalfinance/core').TimeInForce`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`execution.timeInForce.expireAtSessionClose` `boolean`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`initialCapital` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`ledger` `{ sourceId: string; accountId: string; lotRelief: string; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`ledger.accountId` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`ledger.lotRelief` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`ledger.sourceId` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`periodsPerYear` `number`	per year (count)	Required / declared member No @default declared; consult the signature and description.
`portfolioConstruction` `{ method: WeightingMethod; long: SideSelection; short: ShortSideSelection \| null; neutrality: Neutrality; maximumPositions: number \| null; maximumPositionWeight: number \| null; minimumPositionWeight: number \| null; maximumTurnover: number \| null; maximumParticipation: number \| null; volatilityLookbackSessions: number; shortBookSizing: string; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`portfolioConstruction.long` `SideSelection`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`portfolioConstruction.long.count` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`portfolioConstruction.long.fraction` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`portfolioConstruction.long.topQuantile` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`portfolioConstruction.maximumParticipation` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`portfolioConstruction.maximumPositionWeight` `number \| null`	decimal fraction / multiple	Required / declared member No @default declared; consult the signature and description.
`portfolioConstruction.maximumPositions` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`portfolioConstruction.maximumTurnover` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`portfolioConstruction.method` `WeightingMethod`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`portfolioConstruction.minimumPositionWeight` `number \| null`	decimal fraction / multiple	Required / declared member No @default declared; consult the signature and description.
`portfolioConstruction.neutrality` `Neutrality`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`portfolioConstruction.short` `ShortSideSelection \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`portfolioConstruction.short.bottomQuantile` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`portfolioConstruction.short.count` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`portfolioConstruction.short.fraction` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`portfolioConstruction.shortBookSizing` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`portfolioConstruction.volatilityLookbackSessions` `number`	trading sessions	Required / declared member No @default declared; consult the signature and description.
`pricing` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`rebalanceSchedule` `{ frequency: RebalanceFrequency; session: 'open' \| 'close'; bufferBand: number \| null; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`rebalanceSchedule.bufferBand` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`rebalanceSchedule.frequency` `RebalanceFrequency`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`rebalanceSchedule.session` `'open' \| 'close'`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`replayable` `boolean`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`riskFreeRate` `number`	decimal rate (0.05 = 5%)	Required / declared member No @default declared; consult the signature and description.
`seed` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`sessionInstantConvention` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`signal` `{ kind: 'factor-recipe'; recipeName: string; recipeVersion: number; direction: string; lagTradingSessions: number; neutralization: string; } \| { kind: 'score'; components: number; missingValuePolicy: string; } \| { kind: 'screen'; orderBy: string[]; missingValuePolicy: string; } \| { kind: 'callback'; replayable: false; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`signal.components` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`signal.direction` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`signal.kind` `('callback') \| ('factor-recipe') \| ('score') \| ('screen')`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`signal.lagTradingSessions` `number`	trading sessions	Required / declared member No @default declared; consult the signature and description.
`signal.missingValuePolicy` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`signal.neutralization` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`signal.orderBy` `string[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`signal.recipeName` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`signal.recipeVersion` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`signal.replayable` `false`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`universeId` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`window` `{ fromTimestampMs: EpochMs \| null; toTimestampMs: EpochMs \| null; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`window.fromTimestampMs` `number \| null`	epoch milliseconds (UTC instant)	Required / declared member No @default declared; consult the signature and description.
`window.toTimestampMs` `number \| null`	epoch milliseconds (UTC instant)	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

CrossSectionalAttribution

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface CrossSectionalAttribution {
    perRebalance: AttributionRow[];
    /** Mean rank information coefficient per horizon (in rebalances), across rebalances. */
    decay: Array<{
        horizonRebalances: number;
        meanRankInformationCoefficient: number | null;
        samples: number;
    }>;
    meanInformationCoefficient: number | null;
    meanRankInformationCoefficient: number | null;
    meanSpreadReturn: number | null;
}

Fields, parameters & returned members (5)

Name / type	Meaning & unit	Optional / default
`decay` `{ horizonRebalances: number; meanRankInformationCoefficient: number \| null; samples: number; }[]`	Mean rank information coefficient per horizon (in rebalances), across rebalances. unitless by name	Required / declared member No @default declared; consult the signature and description.
`meanInformationCoefficient` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`meanRankInformationCoefficient` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`meanSpreadReturn` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`perRebalance` `AttributionRow[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

CrossSectionalBacktestGridRequest

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface CrossSectionalBacktestGridRequest {
    /** The base request every variation is applied to; validated once, never mutated. */
    request: CrossSectionalBacktestRequest;
    /** The axes; the cartesian product is run with the last axis varying fastest. */
    variations: readonly GridVariation[];
    /** Variations the sweep may run (default 256, at most 4,096). */
    maximumVariations?: number;
    /** The metric that picks the best trial (default `'sharpe'`); ties resolve to the lower index. */
    selectionMetric?: GridSelectionMetric;
    hygiene?: {
        /** CSCV blocks for `probabilityOfBacktestOverfitting` (even, 4–16). Default: 16, or the largest even count the run's periods allow. */
        splits?: number;
        /** `researchProtocol`'s confidence in (0, 1); default 0.95. */
        confidence?: number;
    };
}

Fields, parameters & returned members (183)

This large namespace is split into complete field pages. No fields are omitted.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

CrossSectionalBacktestGridResult

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface CrossSectionalBacktestGridResult {
    /** The parent sweep hash: the content hash of the axes and every child run hash. */
    sweepId: string;
    variations: GridVariationRow[];
    /** Every child run, index-aligned with `variations` — the same function, called once per point. */
    runs: CrossSectionalBacktestResult[];
    /** The best trial by the selection metric, or `null` when no variation carries the metric. */
    best: {
        index: number;
        runId: string;
        metric: GridSelectionMetric;
        value: number;
    } | null;
    hygiene: GridHygiene;
    assumptions: GridAssumptions;
    diagnostics: GridDiagnostics;
}

Fields, parameters & returned members (101)

Name / type	Meaning & unit	Optional / default
`assumptions` `GridAssumptions`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.conventionsVersion` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.hygiene` `{ splits: number \| null; confidence: number; degenerateTrialSharpe: 0; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.hygiene.confidence` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.hygiene.degenerateTrialSharpe` `0`	The trial Sharpe recorded for a degenerate return series. unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.hygiene.splits` `number \| null`	The CSCV blocks actually used, or `null` when the overfitting probability was not computed. unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.maximumVariations` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.paths` `string[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.periodsPerYear` `number`	per year (count)	Required / declared member No @default declared; consult the signature and description.
`assumptions.riskFreeRate` `number`	decimal rate (0.05 = 5%)	Required / declared member No @default declared; consult the signature and description.
`assumptions.selectionMetric` `GridSelectionMetric`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.variationCount` `number`	count (integer)	Required / declared member No @default declared; consult the signature and description.
`best` `{ index: number; metric: GridSelectionMetric; runId: string; value: number; } \| null`	The best trial by the selection metric, or `null` when no variation carries the metric. unitless by name	Required / declared member No @default declared; consult the signature and description.
`best.index` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`best.metric` `GridSelectionMetric`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`best.runId` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`best.value` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics` `GridDiagnostics`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.autoReason` `string`	When a meta-engine (e.g. `engines.auto()`) selected a delegate, this is a one-sentence, human-readable explanation of WHY that delegate was chosen (`engine` then names the delegate). Absent when no auto-selection took place. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.converged` `boolean`	Whether an iterative procedure converged. `false` means the value is not trustworthy. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.decomposition` `Record<string, number>`	Named intermediate quantities the value decomposes into — a par spread's protection leg and risky annuity, a forward variance's near/far legs. The H-series explain paths disclose their arithmetic here so a caller can audit the ratio, not just receive it (3B.3). unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.degenerateTrialCount` `number`	count (integer)	Required / declared member No @default declared; consult the signature and description.
`diagnostics.engine` `string`	Pricing/solver engine name, e.g. `black-scholes-merton`. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.finiteDifferenceBumps` `Record<string, number>`	Finite-difference engines: the ACTUAL bump sizes used for FD Greeks (spec P2.3) — adaptive near the vol/time boundaries, so the caller can see exactly what was differenced. Keys: `spotStep`, `volatilityStep`, `timeStepYears`, `rateStep`, and — extended Greeks only — `dividendYieldStep`. Each is the actual step differenced, in the unit of the coordinate it bumps. (This doc named the retired `hS`/`hSig`/`hT`/`hR`/`hQ` keys for one release after the emit sites had moved to the semantic names, so a caller following it read `undefined`.) unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.iterations` `number`	Iteration count for iterative methods. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.method` `string`	Numerical method, e.g. `closed-form`, `brent`, `finite-difference`. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.selection` `import('@insiderfinance/totalfinance/core/pricing').SelectionReport`	The structured engine-selection report (Gate C, `@insiderfinance/totalfinance/core/pricing`): who was selected, why, and — for automatic selection — every candidate considered with its verdict. This is the machine-readable superset of `engine` + `autoReason` (which remain for compatibility); `selected.name` always agrees with `engine` when both are present. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.selection.candidates` `readonly import('@insiderfinance/totalfinance/core/pricing').SelectionCandidate[]`	Candidates an automatic selection considered; absent for explicit mode. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.selection.mode` `'explicit' \| 'automatic'`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.reason` `string`	Why the selected engine answers this request. unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.selected` `{ name: string; version?: string; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.selected.name` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.selected.version` `string`	unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.skippedHygiene` `{ block: 'researchProtocol' \| 'backtestOverfitting' \| 'deflatedSharpe'; reason: string; }[]`	The hygiene blocks that were not computed, each with its reason. unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.timingMs` `number`	Wall-clock timing in milliseconds, when measured. milliseconds	Optional No @default declared; consult the signature and description.
`diagnostics.variationCount` `number`	count (integer)	Required / declared member No @default declared; consult the signature and description.
`diagnostics.warmup` `number`	Series facades: number of leading output slots that are warmup sentinels (null/NaN) while the computation seeds. Equals the input length when the indicator never emitted. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.warnings` `QuantWarning[]`	Structured warnings; always present (possibly empty). unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene` `GridHygiene`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.backtestOverfitting` `BacktestOverfittingProbabilityResult \| null`	`probabilityOfBacktestOverfitting` over the periods × variations return matrix; `null` when fewer than two variations or too few periods. unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.backtestOverfitting.assumptions` `{ [k: string]: unknown; conventionsVersion: string; }`	Applied conventions, echoed (Law 2 report grammar). unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.backtestOverfitting.assumptions.conventionsVersion` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.backtestOverfitting.backtestOverfittingProbability` `number`	Probability of backtest overfitting: the fraction of the `C(S, S/2)` symmetric train/test splits on which the in-sample-best configuration ranks below the out-of-sample median (logit `λ < 0`). Near `0.5` for noise (selection is worthless out of sample), near `0` for a genuinely persistent edge. unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.backtestOverfitting.combinations` `number`	Number of symmetric train/test splits evaluated: `C(S, S/2)`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.backtestOverfitting.diagnostics` `{ warnings: QuantWarning[]; }`	Structured warnings; always present (possibly empty). unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.backtestOverfitting.diagnostics.warnings` `QuantWarning[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.backtestOverfitting.medianLogit` `number`	Median logit `λ = ln(r̄/(1−r̄))` across the splits (`r̄` = OOS relative rank of the IS-best); `< 0` ⇒ overfit-leaning. unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.backtestOverfitting.observations` `number`	Observations (rows) used after trimming to a multiple of `S`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.backtestOverfitting.splits` `number`	Blocks `S` actually used. unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.backtestOverfitting.trials` `number`	Number of strategy configurations (columns) `N`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.deflatedSharpe` `DeflatedSharpeResult \| null`	`deflatedSharpeRatio` for the best trial against the pool; `null` when the best trial is degenerate. unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.deflatedSharpe.assumptions` `{ [k: string]: unknown; conventionsVersion: string; }`	Applied conventions, echoed (Law 2 report grammar). unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.deflatedSharpe.assumptions.conventionsVersion` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.deflatedSharpe.deflatedSharpe` `number \| null`	`null` when the statistics carry no Sharpe (a zero-variance series). unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.deflatedSharpe.diagnostics` `{ warnings: QuantWarning[]; }`	Structured warnings; always present (possibly empty). unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.deflatedSharpe.diagnostics.warnings` `QuantWarning[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.deflatedSharpe.expectedMaxSharpe` `number`	Expected maximum Sharpe across `trialCount` under the null — the deflation benchmark `SR₀`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.deflatedSharpe.probabilisticSharpe` `number \| null`	The un-deflated PSR (benchmark 0), for comparison. unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.deflatedSharpe.trialCount` `number`	count (integer)	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol` `ResearchVerdict \| null`	`researchProtocol` over the best trial's returns with the pool; `null` when the best trial is degenerate. unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.assumptions` `{ confidence: number; conventionsVersion: string; periodsPerYear: number; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.assumptions.confidence` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.assumptions.conventionsVersion` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.assumptions.periodsPerYear` `number`	per year (count)	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.deflatedSharpe` `number \| null`	Probability the true Sharpe beats the selection-adjusted benchmark SR₀; `null` with `inSample.sharpe`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.diagnostics` `Diagnostics`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.diagnostics.autoReason` `string`	When a meta-engine (e.g. `engines.auto()`) selected a delegate, this is a one-sentence, human-readable explanation of WHY that delegate was chosen (`engine` then names the delegate). Absent when no auto-selection took place. unitless by name	Optional No @default declared; consult the signature and description.
`hygiene.researchProtocol.diagnostics.converged` `boolean`	Whether an iterative procedure converged. `false` means the value is not trustworthy. unitless by name	Optional No @default declared; consult the signature and description.
`hygiene.researchProtocol.diagnostics.decomposition` `Record<string, number>`	Named intermediate quantities the value decomposes into — a par spread's protection leg and risky annuity, a forward variance's near/far legs. The H-series explain paths disclose their arithmetic here so a caller can audit the ratio, not just receive it (3B.3). unitless by name	Optional No @default declared; consult the signature and description.
`hygiene.researchProtocol.diagnostics.engine` `string`	Pricing/solver engine name, e.g. `black-scholes-merton`. unitless by name	Optional No @default declared; consult the signature and description.
`hygiene.researchProtocol.diagnostics.finiteDifferenceBumps` `Record<string, number>`	Finite-difference engines: the ACTUAL bump sizes used for FD Greeks (spec P2.3) — adaptive near the vol/time boundaries, so the caller can see exactly what was differenced. Keys: `spotStep`, `volatilityStep`, `timeStepYears`, `rateStep`, and — extended Greeks only — `dividendYieldStep`. Each is the actual step differenced, in the unit of the coordinate it bumps. (This doc named the retired `hS`/`hSig`/`hT`/`hR`/`hQ` keys for one release after the emit sites had moved to the semantic names, so a caller following it read `undefined`.) unitless by name	Optional No @default declared; consult the signature and description.
`hygiene.researchProtocol.diagnostics.iterations` `number`	Iteration count for iterative methods. unitless by name	Optional No @default declared; consult the signature and description.
`hygiene.researchProtocol.diagnostics.method` `string`	Numerical method, e.g. `closed-form`, `brent`, `finite-difference`. unitless by name	Optional No @default declared; consult the signature and description.
`hygiene.researchProtocol.diagnostics.selection` `import('@insiderfinance/totalfinance/core/pricing').SelectionReport`	The structured engine-selection report (Gate C, `@insiderfinance/totalfinance/core/pricing`): who was selected, why, and — for automatic selection — every candidate considered with its verdict. This is the machine-readable superset of `engine` + `autoReason` (which remain for compatibility); `selected.name` always agrees with `engine` when both are present. unitless by name	Optional No @default declared; consult the signature and description.
`hygiene.researchProtocol.diagnostics.selection.candidates` `readonly import('@insiderfinance/totalfinance/core/pricing').SelectionCandidate[]`	Candidates an automatic selection considered; absent for explicit mode. unitless by name	Optional No @default declared; consult the signature and description.
`hygiene.researchProtocol.diagnostics.selection.mode` `'explicit' \| 'automatic'`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.diagnostics.selection.reason` `string`	Why the selected engine answers this request. unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.diagnostics.selection.selected` `{ name: string; version?: string; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.diagnostics.selection.selected.name` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.diagnostics.selection.selected.version` `string`	unitless by name	Optional No @default declared; consult the signature and description.
`hygiene.researchProtocol.diagnostics.timingMs` `number`	Wall-clock timing in milliseconds, when measured. milliseconds	Optional No @default declared; consult the signature and description.
`hygiene.researchProtocol.diagnostics.warmup` `number`	Series facades: number of leading output slots that are warmup sentinels (null/NaN) while the computation seeds. Equals the input length when the indicator never emitted. unitless by name	Optional No @default declared; consult the signature and description.
`hygiene.researchProtocol.diagnostics.warnings` `QuantWarning[]`	Structured warnings; always present (possibly empty). unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.expectedMaxSharpe` `number`	SR₀ — the expected-max Sharpe of `trialCount` under the null (0 for a single hypothesis). unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.inSample` `{ annualizedSharpe: number \| null; observations: number; sharpe: number \| null; }`	Sharpe figures are `null` (C hygiene) when the returns have zero variance; the verdict is then `inconclusive`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.inSample.annualizedSharpe` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.inSample.observations` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.inSample.sharpe` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.minTrackRecordLength` `number`	Observations needed for `deflatedSharpe ≥ confidence` (`Infinity` when SR ≤ SR₀). count (integer)	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.outOfSample` `{ annualizedSharpe: number \| null; degradation: number \| null; sharpe: number \| null; }`	Present when out-of-sample returns are given; `null` figures when either series has zero variance. unitless by name	Optional No @default declared; consult the signature and description.
`hygiene.researchProtocol.outOfSample.annualizedSharpe` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.outOfSample.degradation` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.outOfSample.sharpe` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.probabilisticSharpe` `number \| null`	Un-deflated PSR (benchmark 0), for comparison; `null` with `inSample.sharpe`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.rationale` `string`	Prose an agent relays. unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.trialCount` `number`	count (integer)	Required / declared member No @default declared; consult the signature and description.
`hygiene.researchProtocol.verdict` `'significant' \| 'inconclusive' \| 'likely-overfit'`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`hygiene.trialSharpes` `number[]`	The trial Sharpes in variation order — the pool `researchProtocol` deflates against. unitless by name	Required / declared member No @default declared; consult the signature and description.
`runs` `CrossSectionalBacktestResult[]`	Every child run, index-aligned with `variations` — the same function, called once per point. unitless by name	Required / declared member No @default declared; consult the signature and description.
`sweepId` `string`	The parent sweep hash: the content hash of the axes and every child run hash. unitless by name	Required / declared member No @default declared; consult the signature and description.
`variations` `GridVariationRow[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

CrossSectionalBacktestRequest

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

// ---------------------------------------------------------------------------------------------------
// Request
// ---------------------------------------------------------------------------------------------------
export interface CrossSectionalBacktestRequest {
    dataset: CrossSectionalDataset;
    universeHistory: UniverseHistory;
    signal: CrossSectionalSignal;
    rebalanceSchedule: RebalanceSchedule;
    portfolioConstruction: PortfolioConstruction;
    /** Decision 7's policy; omitted = `execution.simplified()`, and the result says so. */
    execution?: ExecutionPolicy;
    /** Cost models applied to every fill; omitted = the policy's (none for the simplified policy). */
    transactionCostModel?: {
        commission?: CostModel;
        slippage?: SlippageModel;
    };
    /** Default 1,000,000 in `baseCurrency`. */
    initialCapital?: number;
    /** Default `'USD'`. */
    baseCurrency?: string;
    /** Restrict the run to sessions inside the window (inclusive instants). */
    window?: {
        fromTimestampMs?: EpochMs;
        toTimestampMs?: EpochMs;
    };
    /** Default 252. */
    periodsPerYear?: number;
    riskFreeRate?: number;
    /** Seeds the bootstrap confidence intervals of the performance block; absent = none. */
    seed?: number;
}

Fields, parameters & returned members (176)

This large namespace is split into complete field pages. No fields are omitted.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

CrossSectionalBacktestResult

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface CrossSectionalBacktestResult {
    rebalances: RebalanceRow[];
    holdings: HoldingRow[];
    points: EquityPoint[];
    returns: number[];
    trades: Trade[];
    fills: NormalizedFill[];
    ledger: PortfolioLedgerSnapshot;
    timeline: PortfolioTimelineResult;
    attribution: CrossSectionalAttribution;
    benchmark: BenchmarkComparison | null;
    performance: PerformanceSummary;
    /** Bootstrap confidence intervals of the performance block when a seed was given. */
    performanceConfidence: {
        iterations: number;
        seed: number;
        meanTotalReturn: number;
        standardDeviation: number;
        confidenceInterval95: [
            number,
            number
        ];
    } | null;
    finalValue: number;
    runId: string;
    assumptions: CrossSectionalAssumptions;
    diagnostics: CrossSectionalDiagnostics;
}

Fields, parameters & returned members (213)

This large namespace is split into complete field pages. No fields are omitted.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

CrossSectionalDataset

The point-in-time inputs a cross-sectional strategy reads. Prices are return-index levels.

// ---------------------------------------------------------------------------------------------------
// Dataset
// ---------------------------------------------------------------------------------------------------
/** The point-in-time inputs a cross-sectional strategy reads. Prices are return-index levels. */
export interface CrossSectionalDataset {
    /** Features with `availableTimestampMs` — what a decision may see is decided by availability. */
    observations: readonly UniverseObservation[];
    /** Declared fields; nothing is inferred from the data. */
    fieldDefinitions: readonly FieldDefinition[];
    /** Per-instrument per-session simple returns; their session dates are the run's calendar. */
    returns: readonly ReturnObservation[];
    /** A benchmark's per-session simple returns (one `instrumentId`, e.g. an index proxy). */
    benchmarkReturns?: readonly ReturnObservation[];
    /** Grouping for sector-neutral targets and the recipe's sector neutralization. */
    groups?: Readonly<Record<string, string>>;
    /** The observation field that carries size (log market capitalization) for `sector-and-size`. */
    sizeField?: string;
    /** Grouping for the ledger's exposure reports (asset class, strategy, tags). */
    classification?: Readonly<Record<string, InstrumentClassification>>;
    /** Average daily volume in return-index units, for the participation constraint. */
    averageDailyVolumes?: Readonly<Record<string, number>>;
    /** Per-instrument betas for beta-neutral targets. */
    betas?: Readonly<Record<string, number>>;
}

Fields, parameters & returned members (9)

Name / type	Meaning & unit	Optional / default
`averageDailyVolumes` `Readonly<Record<string, number>>`	Average daily volume in return-index units, for the participation constraint. unitless by name	Optional No @default declared; consult the signature and description.
`benchmarkReturns` `readonly ReturnObservation[]`	A benchmark's per-session simple returns (one `instrumentId`, e.g. an index proxy). unitless by name	Optional No @default declared; consult the signature and description.
`betas` `Readonly<Record<string, number>>`	Per-instrument betas for beta-neutral targets. unitless by name	Optional No @default declared; consult the signature and description.
`classification` `Readonly<Record<string, InstrumentClassification>>`	Grouping for the ledger's exposure reports (asset class, strategy, tags). unitless by name	Optional No @default declared; consult the signature and description.
`fieldDefinitions` `readonly FieldDefinition[]`	Declared fields; nothing is inferred from the data. unitless by name	Required / declared member No @default declared; consult the signature and description.
`groups` `Readonly<Record<string, string>>`	Grouping for sector-neutral targets and the recipe's sector neutralization. unitless by name	Optional No @default declared; consult the signature and description.
`observations` `readonly UniverseObservation[]`	Features with `availableTimestampMs` — what a decision may see is decided by availability. unitless by name	Required / declared member No @default declared; consult the signature and description.
`returns` `readonly ReturnObservation[]`	Per-instrument per-session simple returns; their session dates are the run's calendar. unitless by name	Required / declared member No @default declared; consult the signature and description.
`sizeField` `string`	The observation field that carries size (log market capitalization) for `sector-and-size`. unitless by name	Optional No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

CrossSectionalDiagnostics

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface CrossSectionalDiagnostics extends Diagnostics {
    sessionCount: number;
    rebalanceCount: number;
    fillCount: number;
    rejectedFillCount: number;
    exitCount: number;
    delistingCount: number;
    cappedGoalCount: number;
    violatedGoalCount: number;
    /** The ledger's final base-currency NAV minus the reported `finalValue` — always 0 within 1e-9. */
    reconciliationResidual: number;
}

Fields, parameters & returned members (26)

Name / type	Meaning & unit	Optional / default
`autoReason` `string`	When a meta-engine (e.g. `engines.auto()`) selected a delegate, this is a one-sentence, human-readable explanation of WHY that delegate was chosen (`engine` then names the delegate). Absent when no auto-selection took place. unitless by name	Optional No @default declared; consult the signature and description.
`cappedGoalCount` `number`	count (integer)	Required / declared member No @default declared; consult the signature and description.
`converged` `boolean`	Whether an iterative procedure converged. `false` means the value is not trustworthy. unitless by name	Optional No @default declared; consult the signature and description.
`decomposition` `Record<string, number>`	Named intermediate quantities the value decomposes into — a par spread's protection leg and risky annuity, a forward variance's near/far legs. The H-series explain paths disclose their arithmetic here so a caller can audit the ratio, not just receive it (3B.3). unitless by name	Optional No @default declared; consult the signature and description.
`delistingCount` `number`	count (integer)	Required / declared member No @default declared; consult the signature and description.
`engine` `string`	Pricing/solver engine name, e.g. `black-scholes-merton`. unitless by name	Optional No @default declared; consult the signature and description.
`exitCount` `number`	count (integer)	Required / declared member No @default declared; consult the signature and description.
`fillCount` `number`	count (integer)	Required / declared member No @default declared; consult the signature and description.
`finiteDifferenceBumps` `Record<string, number>`	Finite-difference engines: the ACTUAL bump sizes used for FD Greeks (spec P2.3) — adaptive near the vol/time boundaries, so the caller can see exactly what was differenced. Keys: `spotStep`, `volatilityStep`, `timeStepYears`, `rateStep`, and — extended Greeks only — `dividendYieldStep`. Each is the actual step differenced, in the unit of the coordinate it bumps. (This doc named the retired `hS`/`hSig`/`hT`/`hR`/`hQ` keys for one release after the emit sites had moved to the semantic names, so a caller following it read `undefined`.) unitless by name	Optional No @default declared; consult the signature and description.
`iterations` `number`	Iteration count for iterative methods. unitless by name	Optional No @default declared; consult the signature and description.
`method` `string`	Numerical method, e.g. `closed-form`, `brent`, `finite-difference`. unitless by name	Optional No @default declared; consult the signature and description.
`rebalanceCount` `number`	count (integer)	Required / declared member No @default declared; consult the signature and description.
`reconciliationResidual` `number`	The ledger's final base-currency NAV minus the reported `finalValue` — always 0 within 1e-9. unitless by name	Required / declared member No @default declared; consult the signature and description.
`rejectedFillCount` `number`	count (integer)	Required / declared member No @default declared; consult the signature and description.
`selection` `import('@insiderfinance/totalfinance/core/pricing').SelectionReport`	The structured engine-selection report (Gate C, `@insiderfinance/totalfinance/core/pricing`): who was selected, why, and — for automatic selection — every candidate considered with its verdict. This is the machine-readable superset of `engine` + `autoReason` (which remain for compatibility); `selected.name` always agrees with `engine` when both are present. unitless by name	Optional No @default declared; consult the signature and description.
`selection.candidates` `readonly import('@insiderfinance/totalfinance/core/pricing').SelectionCandidate[]`	Candidates an automatic selection considered; absent for explicit mode. unitless by name	Optional No @default declared; consult the signature and description.
`selection.mode` `'explicit' \| 'automatic'`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`selection.reason` `string`	Why the selected engine answers this request. unitless by name	Required / declared member No @default declared; consult the signature and description.
`selection.selected` `{ name: string; version?: string; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`selection.selected.name` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`selection.selected.version` `string`	unitless by name	Optional No @default declared; consult the signature and description.
`sessionCount` `number`	count (integer)	Required / declared member No @default declared; consult the signature and description.
`timingMs` `number`	Wall-clock timing in milliseconds, when measured. milliseconds	Optional No @default declared; consult the signature and description.
`violatedGoalCount` `number`	count (integer)	Required / declared member No @default declared; consult the signature and description.
`warmup` `number`	Series facades: number of leading output slots that are warmup sentinels (null/NaN) while the computation seeds. Equals the input length when the indicator never emitted. unitless by name	Optional No @default declared; consult the signature and description.
`warnings` `import('@insiderfinance/totalfinance/core').QuantWarning[]`	Structured warnings; always present (possibly empty). unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)