@insiderfinance/totalfinance 0.1.0

package/modules/core/dist/diagnostics.js

@@ -0,0 +1,287 @@
+/** Diagnostics and warnings carried by every pro-API result (spec §5.2). */
+import { ErrorCode, InputError } from './errors.js';
+import { ensureKnownKeys, requireArgumentObject } from './invariants.js';
+/** Construct an empty diagnostics object with no warnings. */
+export function emptyDiagnostics() {
+    return { warnings: [] };
+}
+/** Build a warning helper, defaulting severity to `warn`. */
+export function warning(code, message, severity = 'warn', context) {
+    // A warning IS a public payload — a non-string code/message would be served to consumers.
+    if (typeof code !== 'string' || code.length === 0 || typeof message !== 'string') {
+        throw new InputError(`warning: code and message must be strings — warning('data.stale_quote', 'quote is 3h old'). Received (${code === undefined ? 'undefined' : typeof code}, ${message === undefined ? 'undefined' : typeof message}).`, { code: ErrorCode.InputWrongType, context: { field: 'code' } });
+    }
+    return context !== undefined ? { code, message, severity, context } : { code, message, severity };
+}
+/**
+ * Canonical warning codes. Like error codes, these are stable public API — consumers branch on them.
+ * The set is open; packages may add codes, but documented ones do not change without a major version.
+ *
+ * Codes that are BOTH a thrown-error condition and an emitted warning (`implied_volatility.below_intrinsic`,
+ * `implied_volatility.above_max_bound`, `implied_volatility.no_convergence`, `data.crossed_market`, `data.stale_quote`) live only in
+ * {@link ErrorCode} — the single source of truth — and warning sites reference `ErrorCode.*` for the
+ * code string, so no string is duplicated across the two registries (WS2.9).
+ */
+export const WarningCode = {
+    DataLockedMarket: 'data.locked_market',
+    DataZeroBidAsk: 'data.zero_bid_ask',
+    SurfaceExtrapolated: 'volatility.surface_extrapolated',
+    BinomialStepsRoundedOdd: 'binomial.steps_rounded_odd',
+    GreeksNotComputed: 'greeks.not_computed',
+    SuspiciousVolatility: 'input.suspicious_volatility',
+    SuspiciousTime: 'input.suspicious_time',
+    SuspiciousRiskFreeRate: 'input.suspicious_risk_free_rate',
+    SuspiciousReturns: 'input.suspicious_returns',
+    /** The result is NaN/degenerate BY DESIGN (empty series, zero variance) — disclosed, not fabricated. */
+    DegenerateInput: 'input.degenerate',
+    /** Elasticity Λ = Δ·S/V is undefined (price underflowed to 0) — reported as `null`, never NaN/∞. */
+    LambdaUndefined: 'greeks.lambda_undefined',
+    /** Fractional compounding of a ≤−100%-per-interval rate is undefined — reported as `null`, never NaN. */
+    CompoundingUndefined: 'crypto.compounding_undefined',
+    /** Compounded annualization exceeded IEEE-754 range — reported as `null`, never Infinity. */
+    CompoundingOverflow: 'crypto.compounding_overflow',
+    /** A degenerate/collinear covariance was eigenvalue-floored to keep the SPD postcondition. */
+    CovarianceFloored: 'math.covariance_floored',
+    /** Greeks were explicitly requested but this engine cannot compute them — request not honored. */
+    GreeksUnsupportedByEngine: 'greeks.unsupported_by_engine',
+    /** A structural limitation of the model/data the caller should know about (design law #4). */
+    ModelLimitation: 'model.limitation',
+    /** A valid reusable FX quote was supplied but no target required it in this scenario run. */
+    ScenarioUnusedCurrencyConversion: 'scenario.unused_currency_conversion',
+    // ── Phase 3 registry consolidation (P3.1c) — leaf-package warning codes, see ErrorCode note ──
+    BacktestAssignment: 'backtest.assignment',
+    BacktestDataDuplicateTimestamp: 'backtest.data_duplicate_timestamp',
+    BacktestDataNonfinite: 'backtest.data_nonfinite',
+    /** Stage 4.6 (FC8): a benchmark session had no return and counted as 0; the count rides the warning. */
+    BacktestDataMissing: 'backtest.data_missing',
+    /** Stage 4.6 (FC8) — a pre-trade limit rejected an entry (the row names the limit and the values). */
+    BacktestLimitRejected: 'backtest.limit_rejected',
+    /** Stage 4.6 (FC8) — a structure could not fill every leg under the fill policy (the row names the legs). */
+    BacktestComboLegUnfilled: 'backtest.combo_leg_unfilled',
+    /** Stage 4.6 (FC8) — maintenance margin breached under forcedLiquidation 'none'. */
+    BacktestMarginBreach: 'backtest.margin_breach',
+    /** Stage 4.6 (FC8) — a forced close under the declared liquidation policy (the row names the position and the shortfall). */
+    BacktestForcedLiquidation: 'backtest.forced_liquidation',
+    BacktestDataUnsorted: 'backtest.data_unsorted',
+    BacktestEntrySkipped: 'backtest.entry_skipped',
+    /** An open option leg could not be marked from its current-snapshot quote and the request's
+     * named missing-mark fallback was applied (Preview P1) — the count of leg-snapshots is carried. */
+    BacktestMarkFallback: 'backtest.mark_fallback',
+    BacktestLookahead: 'backtest.lookahead',
+    BacktestMarginRejected: 'backtest.margin_rejected',
+    BacktestMarkedAtCost: 'backtest.marked_at_cost',
+    BacktestNegativeCash: 'backtest.negative_cash',
+    BacktestShortRejected: 'backtest.short_rejected',
+    BacktestSignalWarmup: 'backtest.signal_warmup',
+    CryptoCarryArbitrage: 'crypto.carry_arbitrage',
+    CryptoExtremeFunding: 'crypto.extreme_funding',
+    EstimateRiskNeutral: 'estimate.risk_neutral',
+    FlowSweepsNotVenueVerified: 'flow.sweeps_not_venue_verified',
+    HestonCosineExpansionUnstable: 'heston.cosine_expansion_unstable',
+    HestonFellerViolated: 'heston.feller_violated',
+    ImpliedVolatilityBracketExpanded: 'implied_volatility.bracket_expanded',
+    ImpliedVolatilityFlatHistory: 'implied_volatility.flat_history',
+    ImpliedVolatilityLowVega: 'implied_volatility.low_vega',
+    LookbackZeroCarry: 'lookback.zero_carry',
+    MathCovarianceEwmaEffectiveSample: 'math.covariance_ewma_effective_sample',
+    MathCovarianceIllConditioned: 'math.covariance_ill_conditioned',
+    MathCovarianceMethodAuto: 'math.covariance_method_auto',
+    MathCovarianceSingular: 'math.covariance_singular',
+    MonteCarloQuasiMonteCarloDimensionFallback: 'monte_carlo.quasi_monte_carlo_dimension_fallback',
+    OptimizeNotConverged: 'optimize.not_converged',
+    /** A library result reported this warning as a bare sentence; the envelope carries it typed. */
+    OperationUntypedWarning: 'operation.untyped_warning',
+    OptionsDividendsNone: 'options.dividends_none',
+    OptionsDividendsPast: 'options.dividends_past',
+    OptionsExerciseDiscreteDividends: 'options.exercise_discrete_dividends',
+    /** Quote-only chain health was requested; model bounds and implied volatility are not assessed. */
+    OptionsChainHealthModelNotRequested: 'options.chain_health.model_not_requested',
+    PerformanceSuspiciousEquityInput: 'performance.suspicious_equity_input',
+    PerformanceNonFiniteMetric: 'performance.non_finite_metric',
+    /** `analyze` on a series with zero return periods: every metric is null (E3 degenerate summary). */
+    PerformanceEmptySeries: 'performance.empty_series',
+    /** Zero gross exposure: concentration metrics are undefined and reported as null. */
+    RiskZeroGrossExposure: 'risk.zero_gross_exposure',
+    /** `compareEngines`: one or more engines failed to price (per-row detail on the failed rows). */
+    OptionsEngineFailed: 'options.engine_failed',
+    /** `openingRange`: fewer bars than `periods` — the range covers the whole series. */
+    TechnicalAnalysisOpeningRangeTruncated: 'technical_analysis.opening_range_truncated',
+    /** `unusualness`: flat baseline — the z-score is undefined and reported null. */
+    StructureFlatBaseline: 'structure.flat_baseline',
+    /** Surface/model calibration finished without meeting tolerance — best-effort parameters returned. */
+    VolatilityCalibrationNotConverged: 'volatility.calibration_not_converged',
+    PerformanceUndefinedMetric: 'performance.undefined_metric',
+    ResearchSurvivorshipBias: 'research.survivorship_bias',
+    ResearchTrainTestLeakage: 'research.train_test_leakage',
+    /** `probabilityOfBacktestOverfitting`: the oldest rows were trimmed so T divides into S blocks. */
+    ResearchBacktestOverfittingProbabilityTrimmed: 'research.backtest_overfitting_probability_trimmed',
+    RiskBrinsonWeights: 'risk.brinson_weights',
+    RiskCornishFisherConditionalValueAtRiskGaussianFallback: 'risk.cornish_fisher_conditional_value_at_risk_gaussian_fallback',
+    RiskCornishFisherOutOfDomain: 'risk.cornish_fisher_out_of_domain',
+    RiskCostExceedsEdge: 'risk.cost_exceeds_edge',
+    /** FC7 slice 4 (2026-08-29): estimateExpectedReturns received an asOf but no observation
+     * timestamps — nothing could be screened for look-ahead. */
+    RiskAsOfUnscreened: 'risk.as_of_unscreened',
+    /** A frontier point with zero volatility has no Sharpe ratio (reported null with the reason). */
+    RiskZeroVolatilitySharpe: 'risk.zero_volatility_sharpe',
+    /** The constrained maximum return is unbounded (an asset without an upper bound and another
+     * without a lower bound); a `points` grid fell back to a risk-aversion grid. */
+    RiskFrontierUnboundedReturn: 'risk.frontier_unbounded_return',
+    /** Solved frontier points are not monotone in volatility versus expected return. */
+    RiskFrontierNotMonotone: 'risk.frontier_not_monotone',
+    /** One or more requested frontier points could not be solved (kept with their reasons). */
+    RiskFrontierPointsFailed: 'risk.frontier_points_failed',
+    RiskExtremeValueConfidenceOutsideTail: 'risk.extreme_value_confidence_outside_tail',
+    RiskExtremeValueDegenerateFit: 'risk.extreme_value_degenerate_fit',
+    RiskExtremeValueFewExceedances: 'risk.extreme_value_few_exceedances',
+    RiskExtremeValueInfiniteMean: 'risk.extreme_value_infinite_mean',
+    RiskExtremeValueInfiniteVariance: 'risk.extreme_value_infinite_variance',
+    RiskExtremeValueMleFallback: 'risk.extreme_value_mle_fallback',
+    RiskHighCostDrag: 'risk.high_cost_drag',
+    RiskInfeasibleConstraints: 'risk.infeasible_constraints',
+    RiskInfeasibleTangency: 'risk.infeasible_tangency',
+    RiskKellyEstimationNoEdge: 'risk.kelly_estimation_no_edge',
+    RiskKellyEstimationThinSample: 'risk.kelly_estimation_thin_sample',
+    RiskKellyFatTails: 'risk.kelly_fat_tails',
+    RiskKellyNaiveOverbet: 'risk.kelly_naive_overbet',
+    RiskKellyNegativeSum: 'risk.kelly_negative_sum',
+    RiskKellyNoEdge: 'risk.kelly_no_edge',
+    RiskKellyOver: 'risk.kelly_over',
+    RiskKellyUnbounded: 'risk.kelly_unbounded',
+    RiskMeanExcessNoLinearRegion: 'risk.mean_excess_no_linear_region',
+    /** P&L explain: the unexplained residual dominates the total — the greek expansion broke down. */
+    RiskPnlUnexplainedResidual: 'risk.pnl_unexplained_residual',
+    /** `optionsMargin`: a net-short call makes the expiration loss unbounded — `maxLoss` is null. */
+    RiskUnboundedLoss: 'risk.unbounded_loss',
+    StrategyVolatilityFloored: 'strategy.volatility_floored',
+    /** The reward-to-risk ratio is undefined: an unbounded profit or loss, or a zero maximum loss. */
+    StrategyRiskRewardUndefined: 'strategy.risk_reward_undefined',
+    /** `optimizeStrategy`: a candidate's capital requirement is zero — `thesisEvPerCapital` is null. */
+    StrategyOptimizerZeroCapital: 'strategy.optimizer_zero_capital',
+    StructureAggressorUnavailable: 'structure.aggressor_unavailable',
+    StructureContractsSkipped: 'structure.contracts_skipped',
+    /** Repeated contract rows remain additive and may count the same open interest more than once. */
+    StructureDuplicateContractQuotes: 'structure.duplicate_contract_quotes',
+    /** Every supplied quote was excluded; empty sums must not be read as measured zero exposure. */
+    StructureNoEligibleQuotes: 'structure.no_eligible_quotes',
+    VolatilityButterflyArbitrage: 'volatility.butterfly_arbitrage',
+    VolatilityEssviButterfly: 'volatility.essvi_butterfly',
+    VolatilityEssviCalendar: 'volatility.essvi_calendar',
+    VolatilityEssviCalendarData: 'volatility.essvi_calendar_data',
+    VolatilityEssviNotConverged: 'volatility.essvi_not_converged',
+    VolatilityFitInsufficientData: 'volatility.fit_insufficient_data',
+    VolatilityFitUnconverged: 'volatility.fit_unconverged',
+    VolatilityShockDegradedToInterpolated: 'volatility.shock_degraded_to_interpolated',
+    VolatilityShockFloored: 'volatility.shock_floored',
+    VolatilitySkewDeltaExtrapolated: 'volatility.skew_delta_extrapolated',
+    VolatilityObservedSkewUnavailable: 'volatility.observed_skew_unavailable',
+    VolatilityObservedSkewQuoteExcluded: 'volatility.observed_skew_quote_excluded',
+    /** C hygiene — a zero-variance edge has no Kelly fraction: the sizing is null, never an input error. */
+    RiskKellyZeroVariance: 'risk.kelly_zero_variance',
+    /** C hygiene — a zero-variance return series has no Sharpe ratio: the statistic is null. */
+    RiskSharpeUndefined: 'risk.sharpe_undefined',
+    /** B7 — `chainGreeks` returned some rows unchanged; `diagnostics.rows` names each reason. */
+    OptionsChainGreeksRowsSkipped: 'chain_greeks.rows_skipped',
+    VolatilityObservedSkewMissingDelta: 'volatility.observed_skew_missing_delta',
+    VolatilityObservedSkewDuplicateContract: 'volatility.observed_skew_duplicate_contract',
+    VolatilitySsviButterfly: 'volatility.ssvi_butterfly',
+    VolatilitySsviCalendarData: 'volatility.ssvi_calendar_data',
+    VolatilitySsviNotConverged: 'volatility.ssvi_not_converged',
+    VolatilityStickyIndeterminate: 'volatility.sticky_indeterminate',
+    VolatilityStickyWeakFit: 'volatility.sticky_weak_fit',
+    VolatilitySurfaceQuotesSkipped: 'volatility.surface_quotes_skipped',
+    VolatilitySurfaceSparse: 'volatility.surface_sparse',
+    VolatilitySwaptionCubeExtrapolated: 'volatility.swaption_cube_extrapolated',
+    VolatilitySwaptionNodePoorFit: 'volatility.swaption_node_poor_fit',
+    /** Two artifacts under comparison or replay name different producing library versions — a
+     * difference may be a library change rather than a market or parameter change (Stage 4.5). */
+    ArtifactLibraryVersionDiffers: 'artifact.library_version_differs',
+    /** Two artifacts under comparison were computed under different market snapshots — still
+     * comparable, but the reader is told the market moved (Stage 4.5). */
+    ArtifactComparisonDifferentMarket: 'artifact.comparison_different_market',
+    /** Two research runs under comparison were computed over different universes or as-of dates —
+     * still comparable, but the reader is told the population moved (Stage 4.5). */
+    ArtifactComparisonDifferentUniverse: 'artifact.comparison_different_universe',
+    /** A restored curve was evaluated outside its calibrated pillar range under its stored
+     * extrapolation policy — counted and disclosed, never silent (Stage 4.5). */
+    CurveExtrapolated: 'curve.extrapolated',
+};
+/**
+ * Plausibility warnings for the two classic quant footguns (the first-touch law §2.4). Facades stay
+ * silent-and-correct on the plain-value path (a 2200% vol is legal — memecoins exist), but the
+ * `.explain()` envelope should say what it sees. Never throws; returns `[]` when inputs look normal.
+ *   - `vol > 3`         → likely a percent typed as a decimal (`vol: 22` → 2200%).
+ *   - `t > 5` & integer → likely a day count typed as a year fraction (`t: 30` → a 30-year option).
+ *   - `|rate| > 0.5`    → likely a percent typed as a decimal (`rate: 4.5` → a 450% risk-free rate).
+ */
+export function plausibilityWarnings(inputs) {
+    requireArgumentObject('plausibilityWarnings', 'inputs', inputs);
+    ensureKnownKeys('plausibilityWarnings', 'inputs', inputs, [
+        'volatility',
+        'timeToExpiryYears',
+        'riskFreeRate',
+    ]);
+    for (const field of ['volatility', 'timeToExpiryYears', 'riskFreeRate']) {
+        const v = inputs[field];
+        if (v !== undefined && (typeof v !== 'number' || !Number.isFinite(v))) {
+            throw new InputError(`plausibilityWarnings: ${field} must be a finite number when provided. Received ${v === null ? 'null' : typeof v}.`, { code: ErrorCode.InputWrongType, context: { field } });
+        }
+    }
+    const out = [];
+    /**
+     * These warnings TEACH, so every name in them must be a name the caller can type.
+     *
+     * They used to read `vol=0.2 … vol is a decimal`, `t=10 … t is a year fraction`, `rate=0.05 …` and
+     * to serialize their context under `{ t }` and `{ rate }`. None of those fields exist: the inputs
+     * are `volatility`, `timeToExpiryYears` and `riskFreeRate`. A diagnostic whose whole purpose is to
+     * correct a caller cannot name the field wrongly, and a warning context is a public payload — a
+     * consumer reads those keys.
+     *
+     * The local aliases are gone too. They are private and therefore permitted, but they are how the
+     * short names reached the strings in the first place.
+     */
+    const { volatility, timeToExpiryYears, riskFreeRate } = inputs;
+    if (volatility !== undefined && Number.isFinite(volatility) && volatility > 3) {
+        out.push(warning(WarningCode.SuspiciousVolatility, `volatility=${volatility} implies ${(volatility * 100).toFixed(0)}% — volatility is a decimal; did you mean ${(volatility / 100).toFixed(4)}?`, 'info', { volatility }));
+    }
+    if (timeToExpiryYears !== undefined &&
+        Number.isFinite(timeToExpiryYears) &&
+        timeToExpiryYears > 5 &&
+        Number.isInteger(timeToExpiryYears)) {
+        out.push(warning(WarningCode.SuspiciousTime, `timeToExpiryYears=${timeToExpiryYears} is a very long horizon — timeToExpiryYears is a year fraction; if you meant ${timeToExpiryYears} days, use ${timeToExpiryYears}/365 = ${(timeToExpiryYears / 365).toFixed(4)}.`, 'info', { timeToExpiryYears }));
+    }
+    if (riskFreeRate !== undefined && Number.isFinite(riskFreeRate) && Math.abs(riskFreeRate) > 0.5) {
+        out.push(warning(WarningCode.SuspiciousRiskFreeRate, `riskFreeRate=${riskFreeRate} implies a ${(riskFreeRate * 100).toFixed(0)}% risk-free rate — riskFreeRate is a decimal; did you mean ${(riskFreeRate / 100).toFixed(4)}?`, 'info', { riskFreeRate }));
+    }
+    return out;
+}
+/**
+ * The third classic footgun (dx WS-3 / R6): a PRICE or equity series passed where per-period
+ * RETURNS are expected. Returns are decimals (`0.01` = +1%); a series whose mean magnitude
+ * exceeds 0.5 (50% per period) is almost certainly prices — a monotonic 100→160 price series
+ * fed to `sharpe()` yields an absurd-but-silent 117. Warning only, never an error (a genuine
+ * >50%/period return series is legal — it is just worth flagging). Returns `undefined` when the
+ * series looks like returns.
+ */
+export function suspiciousReturnsWarning(returns) {
+    const n = returns.length;
+    if (n === 0)
+        return undefined;
+    let sumAbs = 0;
+    let finite = 0;
+    for (let i = 0; i < n; i++) {
+        const v = returns[i];
+        if (Number.isFinite(v)) {
+            sumAbs += Math.abs(v);
+            finite++;
+        }
+    }
+    if (finite === 0)
+        return undefined;
+    const meanAbs = sumAbs / finite;
+    if (meanAbs <= 0.5)
+        return undefined;
+    return warning(WarningCode.SuspiciousReturns, `mean |value| = ${meanAbs.toFixed(2)} — returns are decimals (0.01 = +1%); did you pass ` +
+        `prices or an equity curve? Convert with simpleReturns(prices) first.`, 'info', { meanAbs });
+}
+//# sourceMappingURL=diagnostics.js.map

package/modules/core/dist/diagnostics.js.map

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

package/modules/core/dist/errors.d.ts

@@ -0,0 +1,324 @@
+/**
+ * TotalFinance error model (spec §7.5).
+ *
+ * Every error carries a machine-readable, SemVer-stable `code` and optional structured `context`.
+ * Codes are public API: tools, MCP clients, and user error handlers branch on them, so they change
+ * only in major versions.
+ */
+export interface QuantErrorOptions {
+    /** Stable, machine-readable code, e.g. `input.negative_spot`. */
+    code: string;
+    /** Structured context for programmatic handling and good error messages. */
+    context?: Record<string, unknown>;
+    /** Underlying cause, preserved on the standard `Error.cause` chain. */
+    cause?: unknown;
+}
+/** Base class for every TotalFinance error. */
+export declare class QuantError extends Error {
+    readonly code: string;
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, options: QuantErrorOptions);
+    /**
+     * Versioned JSON shape. `message` is a non-enumerable Error property, so a bare
+     * `JSON.stringify(error)` used to drop the one field a human needs; `serialization: 1` lets a
+     * consumer detect future shape changes.
+     */
+    toJSON(): {
+        serialization: 1;
+        name: string;
+        code: string;
+        message: string;
+        context?: Record<string, unknown>;
+    };
+}
+/** Invalid or nonsensical input (programmer error or malformed payload). */
+export declare class InputError extends QuantError {
+}
+/** A numerical solver failed to converge. Never silently replaced with a guess (design law #4). */
+export declare class ConvergenceError extends QuantError {
+}
+/** Inputs violate a no-arbitrage condition (e.g. a price below intrinsic value). */
+export declare class ArbitrageError extends QuantError {
+}
+/** A data-quality problem (crossed/locked market, stale quote, bad print). */
+export declare class DataError extends QuantError {
+}
+/** A requested operation is not supported by the selected engine/model/contract. */
+export declare class UnsupportedError extends QuantError {
+}
+/** The library was configured in a contradictory or unusable way. */
+export declare class ConfigurationError extends QuantError {
+}
+/**
+ * A LIBRARY defect surfaced loudly (Law 7 runtime postcondition): a successful facade/analysis
+ * result was about to carry an undisclosed NaN/Infinity. This is never a user-input error — if
+ * you see it, please report it with the inputs; the honest alternatives are `null`-with-reason
+ * or a disclosed diagnostic, and the function failed to produce either.
+ */
+export declare class PostconditionError extends QuantError {
+}
+/** Type guard: is this value a QuantError (and optionally a specific code)? */
+export declare function isQuantError(value: unknown, code?: string): value is QuantError;
+/**
+ * Canonical error codes used in the 0.0.1 surface. The set is open — packages may introduce new
+ * codes — but these are documented and stable.
+ *
+ * Static references to package-private constants let guard-only consumers discard this registry
+ * while retaining the same error classes. Explicit properties preserve the public property order
+ * and literal readonly types, without a second code object or construction side effects.
+ */
+export declare const ErrorCode: {
+    readonly InputNaN: "input.nan";
+    readonly InputNotFinite: "input.not_finite";
+    readonly InputNegativeSpot: "input.negative_spot";
+    readonly InputNegativeStrike: "input.negative_strike";
+    readonly InputNegativeVolatility: "input.negative_volatility";
+    readonly InputNegativeTime: "input.negative_time";
+    readonly InputOutOfRange: "input.out_of_range";
+    readonly InputInvalidEnum: "input.invalid_enum";
+    readonly InputMissingField: "input.missing_field";
+    readonly InputUnknownField: "input.unknown_field";
+    readonly InputWrongType: "input.wrong_type";
+    /** The argument is an object but not the expected SHAPE (right type, wrong slots) — distinct from a
+     * single missing field. Emitted by {@link wrongShapeError}. */
+    readonly InputWrongShape: "input.wrong_shape";
+    readonly ImpliedVolatilityNoConvergence: "implied_volatility.no_convergence";
+    readonly ImpliedVolatilityBelowIntrinsic: "implied_volatility.below_intrinsic";
+    readonly ImpliedVolatilityAboveMax: "implied_volatility.above_max_bound";
+    readonly EngineUnsupportedContract: "engine.unsupported_contract";
+    readonly DataCrossedMarket: "data.crossed_market";
+    readonly DataStaleQuote: "data.stale_quote";
+    readonly SolverNoConvergence: "solver.no_convergence";
+    readonly LinalgNoConvergence: "linalg.no_convergence";
+    readonly LinalgNotPositiveDefinite: "linalg.not_positive_definite";
+    readonly LinalgSingular: "linalg.singular";
+    readonly IntegrationMaxDepth: "integration.max_depth";
+    readonly InterpolationOutOfDomain: "interpolation.out_of_domain";
+    readonly InterpolationDuplicateKnots: "interpolation.duplicate_knots";
+    readonly InterpolationInvalidGrid: "interpolation.invalid_grid";
+    readonly OptimizeInvalidBounds: "optimize.invalid_bounds";
+    readonly VolatilityExpiryNotFound: "volatility.expiry_not_found";
+    readonly VolatilityCalendarArbitrage: "volatility.calendar_arbitrage";
+    readonly StrategyInvalidChartRange: "strategy.invalid_chart_range";
+    /** A calendar/timezone resolution failed (unknown zone, unresolvable local time). Emitted by core's
+     * time layer, which owns the registry — so it lives here, not as a raw inline literal. */
+    readonly TimeTimezoneResolutionFailed: "time.timezone_resolution_failed";
+    /** A pricing path was given a date with no time of day; a valuation instant must name one. */
+    readonly TimeValuationInstantRequired: "time.valuation_instant_required";
+    readonly BacktestDuplicateHandler: "backtest.duplicate_handler";
+    readonly BacktestMixedSymbols: "backtest.mixed_symbols";
+    /** An open option leg has no usable current-snapshot mark (missing, ambiguous, stale, or
+     * unpriceable contract quote) and the request's missing-mark policy is to refuse (Preview P1). */
+    readonly BacktestMarkUnavailable: "backtest.mark_unavailable";
+    /** Stage 4.6 (FC8) — the `reject` intrabar ambiguity policy met a bar where two orders could
+     * have touched in either sequence; the run refuses rather than pick a sequence silently. */
+    readonly BacktestAmbiguousIntrabar: "backtest.ambiguous_intrabar";
+    /** Stage 4.6 (FC8) — a quote fill under `staleQuotes.behavior: 'reject'` met a quote older than the policy's maximum age. */
+    readonly BacktestStaleQuote: "backtest.stale_quote";
+    /** Stage 4.6 (FC8) — a caller-supplied fill model or instrument adapter failed its conformance suite. */
+    readonly BacktestAdapterNonconformant: "backtest.adapter_nonconformant";
+    /** Stage 4.6 (FC8) — a run's row count is above the ceiling one synchronous run may read. */
+    readonly BacktestInputTooLarge: "backtest.input_too_large";
+    /** Stage 4.6 (FC8) — a 'delisted' universe exit with no delistingReturn while a position is open. */
+    readonly BacktestDelistingReturnMissing: "backtest.delisting_return_missing";
+    /** Stage 4.6 (FC8) — a return or feature names an instrument the universe history never lists. */
+    readonly BacktestUniverseMembershipUnknown: "backtest.universe_membership_unknown";
+    /** Stage 4.6 (FC8) — the emitted portfolio events do not fold to the equity the engine reports (an invariant). */
+    readonly BacktestLedgerReconciliationFailed: "backtest.ledger_reconciliation_failed";
+    /** Stage 7B.1 (AT4) — step() or finish() on a trading environment before reset(). */
+    readonly EnvironmentNotReset: "environment.not_reset";
+    /** Stage 7B.1 (AT4) — a rejection row, never thrown: an order id repeated inside an episode (an idempotent retry). */
+    readonly EnvironmentDuplicateOrder: "environment.duplicate_order";
+    /** Stage 7B.1 (AT4) — a rejection row, never thrown: an order that would breach a declared limit. */
+    readonly EnvironmentLimitBreach: "environment.limit_breach";
+    /** Stage 7B.1 (AT4) — a rejection row, never thrown: an order the action mask disallows. */
+    readonly EnvironmentActionDisallowed: "environment.action_disallowed";
+    /** Stage 7B.1 (AT4) — a rejection row, never thrown: an order naming an instrument the environment does not hold. */
+    readonly EnvironmentUnknownInstrument: "environment.unknown_instrument";
+    /** Stage 7B.1 (AT4) — a rejection row, never thrown: an order or cancellation of the wrong shape. */
+    readonly EnvironmentOrderInvalid: "environment.order_invalid";
+    /** Stage 7B.1 (AT4) — a rejection row, never thrown: an action of the wrong shape; the step proceeds as hold. */
+    readonly EnvironmentActionInvalid: "environment.action_invalid";
+    /** Stage 7B.1 (AT4) — a rejection row, never thrown: a step after the episode ended. */
+    readonly EnvironmentEpisodeOver: "environment.episode_over";
+    /** Stage 7B.2 (AT5) — a trade intent or plan that cannot be normalized (a duplicate line, an unknown instrument). */
+    readonly TradePlanInvalid: "trade.plan_invalid";
+    /** Stage 7B.2 (AT5) — preflight denied the plan; a grant cannot be minted over it. */
+    readonly TradePreflightDenied: "trade.preflight_denied";
+    /** Stage 7B.2 (AT5) — an authorization grant that does not cover the execution asked of it (its reasons name the bindings). */
+    readonly TradeGrantInvalid: "trade.grant_invalid";
+    /** Stage 7B.2 (AT5) — an authorization grant past its expiry. */
+    readonly TradeGrantExpired: "trade.grant_expired";
+    /** Repairs B6 — the grant already licensed a submission; a grant is consumed by its first successful one. */
+    readonly TradeGrantConsumed: "trade.grant_consumed";
+    /** Stage 7B.2 (AT5) — an idempotency key already used for a different plan. */
+    readonly TradeIdempotencyConflict: "trade.idempotency_conflict";
+    /** Stage 7B.2 (AT5) — the kill switch is on: every submission refuses until resumed. */
+    readonly TradeHalted: "trade.halted";
+    /** Stage 7B.2 (AT5) — live execution is not available in the open library; adapters ship under AT8. */
+    readonly TradeLiveUnavailable: "trade.live_unavailable";
+    /** Stage 7B.2 (AT5) — an execution-journal event that the order's state cannot accept. */
+    readonly TradeJournalTransitionInvalid: "trade.journal_transition_invalid";
+    /** Stage 7B.2 (AT5) — an operation whose required capabilities the caller did not grant. */
+    readonly OperationCapabilityMissing: "operation.capability_missing";
+    readonly OperationToolFiltered: "operation.tool_filtered";
+    /** Stage 4.6 (FC8) — a grid's cartesian product is above the variations one synchronous sweep may run. */
+    readonly BacktestGridTooLarge: "backtest.grid_too_large";
+    /** Stage 4.6 (FC8) — an options book above the open positions one synchronous book may hold. */
+    readonly BacktestBookTooLarge: "backtest.book_too_large";
+    /** Stage 4.6 (FC8) — a merger or spin-off on an open option leg; the deliverable cannot be adjusted. */
+    readonly BacktestUnsupportedCorporateAction: "backtest.unsupported_corporate_action";
+    /** Stage 7A — the protocol-neutral operation runtime and registry (`@insiderfinance/totalfinance/workflows`). */
+    readonly OperationUnknown: "operation.unknown";
+    readonly OperationRegistrationRefused: "operation.registration_refused";
+    readonly OperationInputTooLarge: "operation.input_too_large";
+    readonly OperationDeadlineExceeded: "operation.deadline_exceeded";
+    readonly OperationCancelled: "operation.cancelled";
+    readonly OperationInternal: "operation.internal";
+    readonly OperationHandleStoreMissing: "operation.handle_store_missing";
+    readonly OperationHandleUnknown: "operation.handle_unknown";
+    readonly OperationHandleKindMismatch: "operation.handle_kind_mismatch";
+    readonly InputLengthMismatch: "input.length_mismatch";
+    readonly McpDeadlineExceeded: "mcp.deadline_exceeded";
+    readonly McpInputTooLarge: "mcp.input_too_large";
+    readonly McpInternalError: "mcp.internal_error";
+    readonly PostconditionNonFinite: "postcondition.non_finite_result";
+    readonly McpUnknownTool: "mcp.unknown_tool";
+    readonly PipelineDuplicateAlias: "pipeline.duplicate_alias";
+    readonly PipelineLengthMismatch: "pipeline.length_mismatch";
+    readonly RegistryAliasConflict: "registry.alias_conflict";
+    readonly RegistryDuplicateAliasRow: "registry.duplicate_alias_row";
+    readonly RegistryDuplicateIndicator: "registry.duplicate_indicator";
+    readonly RegistryUnknownAliasTarget: "registry.unknown_alias_target";
+    readonly SignalUnknownReference: "signal.unknown_reference";
+    readonly SnapshotInvalidVersion: "snapshot.invalid_version";
+    readonly SnapshotKindMismatch: "snapshot.kind_mismatch";
+    readonly SnapshotUnknownKind: "snapshot.unknown_kind";
+    readonly SnapshotUnsupportedVersion: "snapshot.unsupported_version";
+    /**
+     * A value handed to a snapshot restorer is not an envelope. 3B.N7 retired
+     * `snapshot.reserved_field` in the same change: that code guarded a stream serializing its own `v`
+     * into a FLAT snapshot, and the `{ kind, schemaVersion, state }` envelope makes the collision
+     * structurally impossible — indicator state can no longer reach the envelope's own fields.
+     */
+    readonly SnapshotWrongShape: "snapshot.wrong_shape";
+    readonly StrategyDeltaRequired: "strategy.delta_required";
+    readonly StrategyMultiExpiryExpirationAnalytics: "strategy.multi_expiry_expiration_analytics";
+    /** A call-site `expiry` contradicts the expiry materialized on the position's option legs. */
+    readonly StrategyExpiryConflict: "strategy.expiry_conflict";
+    readonly StrategyStrikeUnavailable: "strategy.strike_unavailable";
+    readonly VolatilityForwardUnavailable: "volatility.forward_unavailable";
+    readonly VolatilitySnapshotVersionMismatch: "volatility.snapshot_version_mismatch";
+    /** A lattice's risk-neutral branch probabilities left [0, 1] (drift outran diffusion). */
+    readonly EngineProbabilityOutOfRange: "engine.probability_out_of_range";
+    /** A successful engine result violated a no-arbitrage output bound (e.g. C > S·e^{-qT}). */
+    readonly EngineResultOutOfBounds: "engine.result_out_of_bounds";
+    /** Warning: the engine's grid/truncation is too coarse for the requested regime. */
+    readonly EngineDiscretizationInadequate: "engine.discretization_inadequate";
+    /** The target premium is below the smallest price the solver can resolve to a volatility. */
+    readonly ImpliedVolatilityPriceBelowResolvable: "implied_volatility.price_below_resolvable";
+    /** Warning: covariance condition number too large for the optimizer's answer to be trusted. */
+    readonly RiskIllConditionedCovariance: "risk.ill_conditioned_covariance";
+    /** Warning: the requested tail quantile lies beyond the sample's resolvable range. */
+    readonly RiskQuantileBeyondSample: "risk.quantile_beyond_sample";
+    /** Warning: a calibrated fit deviates materially from its input data (likely arbitrageable). */
+    readonly VolatilityCalibrationFitDeviation: "volatility.calibration_fit_deviation";
+    /** A variance forecast came back negative; the model output cannot be consumed as a variance. */
+    readonly VolatilityNegativeVarianceForecast: "volatility.negative_variance_forecast";
+    /** An iterative series/loop hit its budget without converging; the value is not returned. */
+    readonly MathIterationLimit: "math.iteration_limit";
+    /** Warning: a resting order's prices/quantity were adjusted for a corporate action (split). */
+    readonly BacktestOrderSplitAdjusted: "backtest.order_split_adjusted";
+    /** Warning: a coupon rate looks like a percent typed as a decimal (e.g. 5 for 5%). */
+    readonly InputSuspiciousCouponRate: "input.suspicious_coupon_rate";
+    /** Warning: a yield looks like a percent typed as a decimal (e.g. 5 for 5%). */
+    readonly InputSuspiciousYield: "input.suspicious_yield";
+    /** Warning: model parameters violate the Feller condition; the variance floor is attainable. */
+    readonly ModelFellerConditionViolated: "model.feller_condition_violated";
+    /** A required market observation is absent from the observations handed to a pricer. */
+    readonly PricerRequirementUnsatisfied: "pricer.requirement_unsatisfied";
+    /** A market-requirement descriptor is malformed (unknown kind, missing/mistyped subject field). */
+    readonly PricerRequirementInvalid: "pricer.requirement_invalid";
+    /** A market observation's value has the wrong type/shape for its requirement's kind. */
+    readonly PricerObservationInvalid: "pricer.observation_invalid";
+    /** A pricer failed the behavioral conformance kit (`validatePricer`) against its own fixtures. */
+    readonly PricerNonconformant: "pricer.nonconformant";
+    /** A scenario override or shock matched no used observation, Taylor factor, FX quote, or handler. */
+    readonly ScenarioInstructionUnmatched: "scenario.instruction_unmatched";
+    /** A target's bound pricer returned false from its one preflight `supports` call. */
+    readonly ScenarioTargetUnsupported: "scenario.target_unsupported";
+    /** One base/scenario valuation failed after the complete request and execution plan passed. */
+    readonly ScenarioCellFailed: "scenario.cell_failed";
+    /** A value has no canonical JSON form (Date/Map/Set/typed array/class instance/bigint/function
+     * — or the reserved `{ nonFinite }` wrapper supplied as literal data). The canonical serializer
+     * refuses rather than guessing a meaning into every content hash. */
+    readonly SerializationUnsupportedValue: "serialization.unsupported_value";
+    /** An older-schema envelope was read with no registered migration covering a required step —
+     * schema upgrades are explicit, never silent. */
+    readonly ArtifactMigrationMissing: "artifact.migration_missing";
+    /** A second migration was registered for the same `(kind, fromVersion)` — two upgrades for one
+     * stored shape cannot both be the truth. */
+    readonly ArtifactDuplicateMigration: "artifact.duplicate_migration";
+    /** A saved analysis artifact's `id` does not equal the content hash of its body — the artifact
+     * was edited after creation (or assembled by hand); its provenance chain cannot be trusted. */
+    readonly ArtifactIdMismatch: "artifact.id_mismatch";
+    /** `compareAnalysisArtifacts` received two artifacts of different `artifactType`s — a leaf-by-leaf
+     * comparison across result schemas would compare unrelated numbers under shared names. */
+    readonly ArtifactTypeMismatch: "artifact.type_mismatch";
+    /** A domain artifact verb received an artifact or report of another package, model family, or
+     * research kind (Stage 4.5) — the teaching names the owner. */
+    readonly ArtifactFamilyMismatch: "artifact.family_mismatch";
+    /** A stored fitted-model `modelVersion` / research `runVersion` is newer than this build, or older
+     * with no registered report migration — evaluating a stored parameter set under different
+     * semantics is a silent wrong number, so it is refused (Stage 4.5 Decision 5). */
+    readonly ArtifactModelVersionUnsupported: "artifact.model_version_unsupported";
+    /** The stored inputs carried a non-serializable callback (a custom predicate or expected-return
+     * model); replay cannot re-issue the producing call and names the field (Stage 4.5). */
+    readonly ArtifactNotReplayable: "artifact.not_replayable";
+    /** Caller-supplied rows for a referenced table do not hash to the artifact's table handle — a
+     * replay over different data would be a replay of a different run (Stage 4.5). */
+    readonly ArtifactReferencedDataMismatch: "artifact.referenced_data_mismatch";
+    /** An embedded calibration or run input exceeds `maximumEmbeddedBytes`; the teaching says to
+     * reference the bulk row set through a table handle instead (Stage 4.5 Decision 9). */
+    readonly ArtifactEmbeddedInputTooLarge: "artifact.embedded_input_too_large";
+    /** The model family has no evaluator, warm start, stability, or holdout operation — an exact or
+     * closed-form fit has no search to start and a statistic has nothing to evaluate (Stage 4.5). */
+    readonly ArtifactOperationUnsupported: "artifact.operation_unsupported";
+    /** A `(sourceId, eventId)` pair was replayed with a DIFFERENT event body. The duplicate boundary
+     * makes replay idempotent for identical deliveries; a changed payload under the same identity is
+     * a conflict that must be heard, never a silent overwrite or a silent no-op. */
+    readonly PortfolioDuplicateEventConflict: "portfolio.duplicate_event_conflict";
+    /** A `specific-lot` relief selection names a lot that does not exist in the position or carries
+     * less remaining quantity than the selection claims — lot relief never guesses a substitute. */
+    readonly PortfolioLotUnavailable: "portfolio.lot_unavailable";
+    /** A valuation needs a mark (an instrument price or a currency-pair quote to the base currency)
+     * that the supplied market/conversion inputs do not carry. An unavailable mark is a typed
+     * failure, never an interpolated or stale guess. */
+    readonly PortfolioMarkUnavailable: "portfolio.mark_unavailable";
+    /** An `admin.reversal`/`admin.correction` names an `original` the fold never applied under that
+     * `(sourceId, eventId)` — a reversal repairs an applied fact, never an imagined one. */
+    readonly PortfolioReversalTargetMissing: "portfolio.reversal_target_missing";
+    /** The applied fact cannot be reversed exactly: the supplied `original` differs from what was
+     * applied, it was already reversed, its lots were relieved by later fills, or its family has no
+     * exact inverse in this build. History is never approximated — record a correcting event. */
+    readonly PortfolioReversalInfeasible: "portfolio.reversal_infeasible";
+};
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+/**
+ * Build the canonical "a required field is missing" error (design law #4 / the first-touch law).
+ * One voice across every facade: it names the field and shows a WORKING example call, so the message
+ * teaches the fix instead of leaking a raw `TypeError` from a property access.
+ *
+ * ```
+ * InputError [input.missing_field]: sma: period is required.
+ *   e.g. sma(closes, { period: 20 })
+ * ```
+ */
+export declare function missingFieldError(functionName: string, field: string, example: string, hint?: string): InputError;
+/**
+ * Build a "this object isn't the expected shape" error that echoes the keys the caller DID pass. The
+ * received-keys echo turns the error into documentation of the expected shape — a reasonable wrong
+ * guess (`{ putLongStrike: … }`) is answered with the real slot names rather than a raw `TypeError`.
+ */
+export declare function wrongShapeError(functionName: string, expected: string, received: unknown): InputError;
+//# sourceMappingURL=errors.d.ts.map