@insiderfinance/totalfinance 0.1.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,+CAA+C;AAC/C,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAE/B,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB;IASvD;;;;OAIG;IACH,MAAM,IAAI;QACR,aAAa,EAAE,CAAC,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC;CASF;AAED,4EAA4E;AAC5E,qBAAa,UAAW,SAAQ,UAAU;CAAG;AAE7C,mGAAmG;AACnG,qBAAa,gBAAiB,SAAQ,UAAU;CAAG;AAEnD,oFAAoF;AACpF,qBAAa,cAAe,SAAQ,UAAU;CAAG;AAEjD,8EAA8E;AAC9E,qBAAa,SAAU,SAAQ,UAAU;CAAG;AAE5C,oFAAoF;AACpF,qBAAa,gBAAiB,SAAQ,UAAU;CAAG;AAEnD,qEAAqE;AACrE,qBAAa,kBAAmB,SAAQ,UAAU;CAAG;AAErD;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,UAAU;CAAG;AAErD,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/E;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;IAYpB;mEAC+D;;;;;;;;;;;;;;;;;;;;IAqB/D;8FAC0F;;IAE1F,8FAA8F;;;;IAU9F;sGACkG;;IAElG;gGAC4F;;IAE5F,6HAA6H;;IAE7H,yGAAyG;;IAEzG,6FAA6F;;IAE7F,qGAAqG;;IAErG,kGAAkG;;IAElG,kHAAkH;;IAElH,qFAAqF;;IAErF,sHAAsH;;IAEtH,qGAAqG;;IAErG,4FAA4F;;IAE5F,qHAAqH;;IAErH,qGAAqG;;IAErG,iHAAiH;;IAEjH,wFAAwF;;IAExF,qHAAqH;;IAErH,sFAAsF;;IAEtF,+HAA+H;;IAE/H,iEAAiE;;IAEjE,6GAA6G;;IAE7G,+EAA+E;;IAE/E,wFAAwF;;IAExF,uGAAuG;;IAEvG,0FAA0F;;IAE1F,4FAA4F;;;IAG5F,0GAA0G;;IAE1G,gGAAgG;;IAEhG,wGAAwG;;IAExG,iHAAiH;;;;;;;;;;;;;;;;;;;;;;;;;;;IA2BjH;;;;;OAKG;;;;IAIH,8FAA8F;;;;;IAS9F,0FAA0F;;IAE1F,4FAA4F;;IAE5F,oFAAoF;;IAEpF,6FAA6F;;IAE7F,+FAA+F;;IAE/F,sFAAsF;;IAEtF,gGAAgG;;IAEhG,iGAAiG;;IAEjG,6FAA6F;;IAE7F,+FAA+F;;IAE/F,sFAAsF;;IAEtF,gFAAgF;;IAEhF,gGAAgG;;IAQhG,wFAAwF;;IAExF,mGAAmG;;IAEnG,wFAAwF;;IAExF,kGAAkG;;IAIlG,qGAAqG;;IAErG,qFAAqF;;IAErF,+FAA+F;;IAI/F;;yEAEqE;;IAErE;qDACiD;;IAEjD;gDAC4C;;IAE5C;mGAC+F;;IAE/F;8FAC0F;;IAE1F;mEAC+D;;IAE/D;;sFAEkF;;IAElF;4FACwF;;IAExF;sFACkF;;IAElF;2FACuF;;IAEvF;qGACiG;;IAIjG;;oFAEgF;;IAEhF;oGACgG;;IAEhG;;wDAEoD;;IAEpD;4FACwF;;IAExF;;iGAE6F;;CAErF,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAEnE;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,GACZ,UAAU,CASZ;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,OAAO,GAChB,UAAU,CAYZ"}

package/modules/core/dist/errors.js

@@ -0,0 +1,363 @@
+/**
+ * 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.
+ */
+import * as ValidationCode from './validation-codes.js';
+/** Base class for every TotalFinance error. */
+export class QuantError extends Error {
+    code;
+    context;
+    constructor(message, options) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = new.target.name;
+        this.code = options.code;
+        if (options.context !== undefined)
+            this.context = options.context;
+        // Preserve the prototype chain when compiled to older targets.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    /**
+     * 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() {
+        return {
+            serialization: 1,
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            ...(this.context !== undefined ? { context: this.context } : {}),
+        };
+    }
+}
+/** Invalid or nonsensical input (programmer error or malformed payload). */
+export class InputError extends QuantError {
+}
+/** A numerical solver failed to converge. Never silently replaced with a guess (design law #4). */
+export class ConvergenceError extends QuantError {
+}
+/** Inputs violate a no-arbitrage condition (e.g. a price below intrinsic value). */
+export class ArbitrageError extends QuantError {
+}
+/** A data-quality problem (crossed/locked market, stale quote, bad print). */
+export class DataError extends QuantError {
+}
+/** A requested operation is not supported by the selected engine/model/contract. */
+export class UnsupportedError extends QuantError {
+}
+/** The library was configured in a contradictory or unusable way. */
+export 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 class PostconditionError extends QuantError {
+}
+/** Type guard: is this value a QuantError (and optionally a specific code)? */
+export function isQuantError(value, code) {
+    return value instanceof QuantError && (code === undefined || value.code === code);
+}
+/**
+ * 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 const ErrorCode = {
+    InputNaN: ValidationCode.InputNaN,
+    InputNotFinite: ValidationCode.InputNotFinite,
+    InputNegativeSpot: ValidationCode.InputNegativeSpot,
+    InputNegativeStrike: ValidationCode.InputNegativeStrike,
+    InputNegativeVolatility: ValidationCode.InputNegativeVolatility,
+    InputNegativeTime: ValidationCode.InputNegativeTime,
+    InputOutOfRange: ValidationCode.InputOutOfRange,
+    InputInvalidEnum: ValidationCode.InputInvalidEnum,
+    InputMissingField: ValidationCode.InputMissingField,
+    InputUnknownField: ValidationCode.InputUnknownField,
+    InputWrongType: ValidationCode.InputWrongType,
+    /** The argument is an object but not the expected SHAPE (right type, wrong slots) — distinct from a
+     * single missing field. Emitted by {@link wrongShapeError}. */
+    InputWrongShape: ValidationCode.InputWrongShape,
+    ImpliedVolatilityNoConvergence: 'implied_volatility.no_convergence',
+    ImpliedVolatilityBelowIntrinsic: 'implied_volatility.below_intrinsic',
+    ImpliedVolatilityAboveMax: 'implied_volatility.above_max_bound',
+    EngineUnsupportedContract: 'engine.unsupported_contract',
+    // Reserved for the Phase-8 data-quality layer (crossed/stale quote rejection); kept intentionally.
+    DataCrossedMarket: 'data.crossed_market',
+    DataStaleQuote: 'data.stale_quote',
+    SolverNoConvergence: 'solver.no_convergence',
+    LinalgNoConvergence: 'linalg.no_convergence',
+    LinalgNotPositiveDefinite: 'linalg.not_positive_definite',
+    LinalgSingular: 'linalg.singular',
+    IntegrationMaxDepth: 'integration.max_depth',
+    InterpolationOutOfDomain: 'interpolation.out_of_domain',
+    InterpolationDuplicateKnots: 'interpolation.duplicate_knots',
+    InterpolationInvalidGrid: 'interpolation.invalid_grid',
+    OptimizeInvalidBounds: 'optimize.invalid_bounds',
+    VolatilityExpiryNotFound: 'volatility.expiry_not_found',
+    VolatilityCalendarArbitrage: 'volatility.calendar_arbitrage',
+    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. */
+    TimeTimezoneResolutionFailed: 'time.timezone_resolution_failed',
+    /** A pricing path was given a date with no time of day; a valuation instant must name one. */
+    TimeValuationInstantRequired: 'time.valuation_instant_required',
+    // ── Phase 3 registry consolidation (P3.1c) ──────────────────────────────────────────────────
+    // Every leaf-package error code, registered centrally: the shrink-only legacy ratchet in
+    // tools/codes-conformance.test.ts is now EMPTY and stays empty — an unregistered code anywhere
+    // in the monorepo is a CI failure. Call-site classification: these appear only in typed-error
+    // constructors. Semantics live at the emit sites; the registry guarantees greppable stability.
+    BacktestDuplicateHandler: 'backtest.duplicate_handler',
+    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). */
+    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. */
+    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. */
+    BacktestStaleQuote: 'backtest.stale_quote',
+    /** Stage 4.6 (FC8) — a caller-supplied fill model or instrument adapter failed its conformance suite. */
+    BacktestAdapterNonconformant: 'backtest.adapter_nonconformant',
+    /** Stage 4.6 (FC8) — a run's row count is above the ceiling one synchronous run may read. */
+    BacktestInputTooLarge: 'backtest.input_too_large',
+    /** Stage 4.6 (FC8) — a 'delisted' universe exit with no delistingReturn while a position is open. */
+    BacktestDelistingReturnMissing: 'backtest.delisting_return_missing',
+    /** Stage 4.6 (FC8) — a return or feature names an instrument the universe history never lists. */
+    BacktestUniverseMembershipUnknown: 'backtest.universe_membership_unknown',
+    /** Stage 4.6 (FC8) — the emitted portfolio events do not fold to the equity the engine reports (an invariant). */
+    BacktestLedgerReconciliationFailed: 'backtest.ledger_reconciliation_failed',
+    /** Stage 7B.1 (AT4) — step() or finish() on a trading environment before reset(). */
+    EnvironmentNotReset: 'environment.not_reset',
+    /** Stage 7B.1 (AT4) — a rejection row, never thrown: an order id repeated inside an episode (an idempotent retry). */
+    EnvironmentDuplicateOrder: 'environment.duplicate_order',
+    /** Stage 7B.1 (AT4) — a rejection row, never thrown: an order that would breach a declared limit. */
+    EnvironmentLimitBreach: 'environment.limit_breach',
+    /** Stage 7B.1 (AT4) — a rejection row, never thrown: an order the action mask disallows. */
+    EnvironmentActionDisallowed: 'environment.action_disallowed',
+    /** Stage 7B.1 (AT4) — a rejection row, never thrown: an order naming an instrument the environment does not hold. */
+    EnvironmentUnknownInstrument: 'environment.unknown_instrument',
+    /** Stage 7B.1 (AT4) — a rejection row, never thrown: an order or cancellation of the wrong shape. */
+    EnvironmentOrderInvalid: 'environment.order_invalid',
+    /** Stage 7B.1 (AT4) — a rejection row, never thrown: an action of the wrong shape; the step proceeds as hold. */
+    EnvironmentActionInvalid: 'environment.action_invalid',
+    /** Stage 7B.1 (AT4) — a rejection row, never thrown: a step after the episode ended. */
+    EnvironmentEpisodeOver: 'environment.episode_over',
+    /** Stage 7B.2 (AT5) — a trade intent or plan that cannot be normalized (a duplicate line, an unknown instrument). */
+    TradePlanInvalid: 'trade.plan_invalid',
+    /** Stage 7B.2 (AT5) — preflight denied the plan; a grant cannot be minted over it. */
+    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). */
+    TradeGrantInvalid: 'trade.grant_invalid',
+    /** Stage 7B.2 (AT5) — an authorization grant past its expiry. */
+    TradeGrantExpired: 'trade.grant_expired',
+    /** Repairs B6 — the grant already licensed a submission; a grant is consumed by its first successful one. */
+    TradeGrantConsumed: 'trade.grant_consumed',
+    /** Stage 7B.2 (AT5) — an idempotency key already used for a different plan. */
+    TradeIdempotencyConflict: 'trade.idempotency_conflict',
+    /** Stage 7B.2 (AT5) — the kill switch is on: every submission refuses until resumed. */
+    TradeHalted: 'trade.halted',
+    /** Stage 7B.2 (AT5) — live execution is not available in the open library; adapters ship under AT8. */
+    TradeLiveUnavailable: 'trade.live_unavailable',
+    /** Stage 7B.2 (AT5) — an execution-journal event that the order's state cannot accept. */
+    TradeJournalTransitionInvalid: 'trade.journal_transition_invalid',
+    /** Stage 7B.2 (AT5) — an operation whose required capabilities the caller did not grant. */
+    OperationCapabilityMissing: 'operation.capability_missing',
+    OperationToolFiltered: 'operation.tool_filtered',
+    /** Stage 4.6 (FC8) — a grid's cartesian product is above the variations one synchronous sweep may run. */
+    BacktestGridTooLarge: 'backtest.grid_too_large',
+    /** Stage 4.6 (FC8) — an options book above the open positions one synchronous book may hold. */
+    BacktestBookTooLarge: 'backtest.book_too_large',
+    /** Stage 4.6 (FC8) — a merger or spin-off on an open option leg; the deliverable cannot be adjusted. */
+    BacktestUnsupportedCorporateAction: 'backtest.unsupported_corporate_action',
+    /** Stage 7A — the protocol-neutral operation runtime and registry (`@insiderfinance/totalfinance/workflows`). */
+    OperationUnknown: 'operation.unknown',
+    OperationRegistrationRefused: 'operation.registration_refused',
+    OperationInputTooLarge: 'operation.input_too_large',
+    OperationDeadlineExceeded: 'operation.deadline_exceeded',
+    OperationCancelled: 'operation.cancelled',
+    OperationInternal: 'operation.internal',
+    OperationHandleStoreMissing: 'operation.handle_store_missing',
+    OperationHandleUnknown: 'operation.handle_unknown',
+    OperationHandleKindMismatch: 'operation.handle_kind_mismatch',
+    InputLengthMismatch: ValidationCode.InputLengthMismatch,
+    McpDeadlineExceeded: 'mcp.deadline_exceeded',
+    McpInputTooLarge: 'mcp.input_too_large',
+    McpInternalError: 'mcp.internal_error',
+    PostconditionNonFinite: ValidationCode.PostconditionNonFinite,
+    McpUnknownTool: 'mcp.unknown_tool',
+    PipelineDuplicateAlias: 'pipeline.duplicate_alias',
+    PipelineLengthMismatch: 'pipeline.length_mismatch',
+    RegistryAliasConflict: 'registry.alias_conflict',
+    RegistryDuplicateAliasRow: 'registry.duplicate_alias_row',
+    RegistryDuplicateIndicator: 'registry.duplicate_indicator',
+    RegistryUnknownAliasTarget: 'registry.unknown_alias_target',
+    SignalUnknownReference: 'signal.unknown_reference',
+    SnapshotInvalidVersion: 'snapshot.invalid_version',
+    SnapshotKindMismatch: 'snapshot.kind_mismatch',
+    SnapshotUnknownKind: 'snapshot.unknown_kind',
+    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.
+     */
+    SnapshotWrongShape: 'snapshot.wrong_shape',
+    StrategyDeltaRequired: 'strategy.delta_required',
+    StrategyMultiExpiryExpirationAnalytics: 'strategy.multi_expiry_expiration_analytics',
+    /** A call-site `expiry` contradicts the expiry materialized on the position's option legs. */
+    StrategyExpiryConflict: 'strategy.expiry_conflict',
+    StrategyStrikeUnavailable: 'strategy.strike_unavailable',
+    VolatilityForwardUnavailable: 'volatility.forward_unavailable',
+    VolatilitySnapshotVersionMismatch: 'volatility.snapshot_version_mismatch',
+    // ── 2026-08-02 defect-fix wave ──────────────────────────────────────────────────────────────
+    // Registered ahead of their emit sites (which land in the same PR) so the fix slices cannot race
+    // on this registry. Each closes a reviewed silent-wrong-number or fabricated-success defect.
+    /** A lattice's risk-neutral branch probabilities left [0, 1] (drift outran diffusion). */
+    EngineProbabilityOutOfRange: 'engine.probability_out_of_range',
+    /** A successful engine result violated a no-arbitrage output bound (e.g. C > S·e^{-qT}). */
+    EngineResultOutOfBounds: 'engine.result_out_of_bounds',
+    /** Warning: the engine's grid/truncation is too coarse for the requested regime. */
+    EngineDiscretizationInadequate: 'engine.discretization_inadequate',
+    /** The target premium is below the smallest price the solver can resolve to a volatility. */
+    ImpliedVolatilityPriceBelowResolvable: 'implied_volatility.price_below_resolvable',
+    /** Warning: covariance condition number too large for the optimizer's answer to be trusted. */
+    RiskIllConditionedCovariance: 'risk.ill_conditioned_covariance',
+    /** Warning: the requested tail quantile lies beyond the sample's resolvable range. */
+    RiskQuantileBeyondSample: 'risk.quantile_beyond_sample',
+    /** Warning: a calibrated fit deviates materially from its input data (likely arbitrageable). */
+    VolatilityCalibrationFitDeviation: 'volatility.calibration_fit_deviation',
+    /** A variance forecast came back negative; the model output cannot be consumed as a variance. */
+    VolatilityNegativeVarianceForecast: 'volatility.negative_variance_forecast',
+    /** An iterative series/loop hit its budget without converging; the value is not returned. */
+    MathIterationLimit: 'math.iteration_limit',
+    /** Warning: a resting order's prices/quantity were adjusted for a corporate action (split). */
+    BacktestOrderSplitAdjusted: 'backtest.order_split_adjusted',
+    /** Warning: a coupon rate looks like a percent typed as a decimal (e.g. 5 for 5%). */
+    InputSuspiciousCouponRate: ValidationCode.InputSuspiciousCouponRate,
+    /** Warning: a yield looks like a percent typed as a decimal (e.g. 5 for 5%). */
+    InputSuspiciousYield: ValidationCode.InputSuspiciousYield,
+    /** Warning: model parameters violate the Feller condition; the variance floor is attainable. */
+    ModelFellerConditionViolated: 'model.feller_condition_violated',
+    // ── Gate C structural extension contracts (docs/specs/gate-c-extension-contracts.md) ────────
+    // The Pricer/requirements protocol in `@insiderfinance/totalfinance/core/pricing` emits these; they are registered
+    // here because core owns the registry (F15) and because the conformance kit BRANCHES on
+    // `pricer.requirement_unsatisfied` — a third-party pricer must throw exactly this code for a
+    // missing required observation, so the code is load-bearing public API from its first commit.
+    /** A required market observation is absent from the observations handed to a pricer. */
+    PricerRequirementUnsatisfied: 'pricer.requirement_unsatisfied',
+    /** A market-requirement descriptor is malformed (unknown kind, missing/mistyped subject field). */
+    PricerRequirementInvalid: 'pricer.requirement_invalid',
+    /** A market observation's value has the wrong type/shape for its requirement's kind. */
+    PricerObservationInvalid: 'pricer.observation_invalid',
+    /** A pricer failed the behavioral conformance kit (`validatePricer`) against its own fixtures. */
+    PricerNonconformant: 'pricer.nonconformant',
+    // ── Stage 4.4b shared cross-domain scenario runner (`@insiderfinance/totalfinance/scenarios`) ────────────────
+    /** A scenario override or shock matched no used observation, Taylor factor, FX quote, or handler. */
+    ScenarioInstructionUnmatched: 'scenario.instruction_unmatched',
+    /** A target's bound pricer returned false from its one preflight `supports` call. */
+    ScenarioTargetUnsupported: 'scenario.target_unsupported',
+    /** One base/scenario valuation failed after the complete request and execution plan passed. */
+    ScenarioCellFailed: 'scenario.cell_failed',
+    // ── Gate B artifact spine (`@insiderfinance/totalfinance/core/artifacts`) ──────────────────────────────────────
+    /** 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. */
+    SerializationUnsupportedValue: 'serialization.unsupported_value',
+    /** An older-schema envelope was read with no registered migration covering a required step —
+     * schema upgrades are explicit, never silent. */
+    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. */
+    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. */
+    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. */
+    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. */
+    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). */
+    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). */
+    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). */
+    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). */
+    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). */
+    ArtifactOperationUnsupported: 'artifact.operation_unsupported',
+    // ── FC7 durable portfolio ledger (`@insiderfinance/totalfinance/portfolio`) ────────────────────────────────────
+    /** 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. */
+    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. */
+    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. */
+    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. */
+    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. */
+    PortfolioReversalInfeasible: 'portfolio.reversal_infeasible',
+};
+/**
+ * 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 function missingFieldError(functionName, field, example, hint) {
+    const lines = [`${functionName}: ${field} is required.`, `  e.g. ${example}`];
+    // The hint carries what the call shape cannot: a unit trap, a range, a name collision. It is a
+    // SECOND line rather than a replacement, because the example has to stay pasteable.
+    if (hint !== undefined)
+        lines.push(`  ${field}: ${hint}`);
+    return new InputError(lines.join('\n'), {
+        code: ValidationCode.InputMissingField,
+        context: { function: functionName, field, example, ...(hint === undefined ? {} : { hint }) },
+    });
+}
+/**
+ * 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 function wrongShapeError(functionName, expected, received) {
+    const keys = received !== null && typeof received === 'object' ? Object.keys(received) : [];
+    return new InputError(`${functionName}: expected ${expected}.\n  received keys: ${keys.length > 0 ? keys.join(', ') : '(none)'}`, {
+        // A wrong-shape object is not a single missing field — it has its own code so a caller/agent can
+        // dispatch on "you passed the wrong slots" separately from "you omitted one field" (F15).
+        code: ValidationCode.InputWrongShape,
+        context: { function: functionName, expected, receivedKeys: keys },
+    });
+}
+//# sourceMappingURL=errors.js.map

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

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

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

@@ -0,0 +1,97 @@
+/**
+ * The facade pattern (design law #1 / §5.1): a plain callable paired with an `.explain()` companion.
+ *
+ * `f(input)` returns the bare value (and throws typed errors on failure); `f.explain(input)` returns
+ * the full {@link Computed} envelope (value + assumptions + diagnostics). One gesture, everywhere —
+ * lifted into core so every package builds its scalar facades the same way (DX1).
+ *
+ * Both constructors guard the FIRST argument centrally (the first-touch law, dx §7.1): a facade
+ * called with `undefined`, a string, or a number throws a typed teaching `InputError` here, before
+ * any property access inside the wrapped implementation can escape as a raw `TypeError`. The guard
+ * only checks the container shape — field-level validation stays inside each facade, where the
+ * domain knowledge lives.
+ */
+import type { Computed } from './computed.js';
+/**
+ * Law 7 runtime postcondition (spec P2.1, tightened in E3): a SUCCESSFUL explained result is
+ * JSON-safe — it NEVER carries a non-finite number (`JSON.stringify` would silently corrupt it to
+ * `null`). **Warnings never license a non-finite value**: an undefined quantity is reported as
+ * `null` and the warning explains the null. The only ratified exceptions are structural sentinels:
+ *
+ *   1. `diagnostics.warmup > 0` with an array value — EXACTLY the first `warmup` slots are the
+ *      documented aligned-series "not yet formed" sentinel; every slot past the prefix is checked;
+ *   2. discriminated "none" elements — zone-style points (`direction: 0`, shape-anchored on their
+ *      zone fields) and divergence points (`code: 0`, shape-anchored on `priceSwings`) — whose
+ *      documented NaN-when-none fields are exempt; every OTHER field of such an element is still
+ *      checked, and an element that merely says `direction: 0` without the zone shape (e.g. an
+ *      honest tdSequential point) is walked in full.
+ *
+ * Anything else non-finite throws {@link PostconditionError}: a library defect surfaced loudly at
+ * the boundary rather than shipped silently into a serialization. The walk is exhaustive — full
+ * depth (cycle-safe), value + assumptions + diagnostics + provenance — so nothing hides below a cap.
+ */
+export declare function assertFiniteResult(label: string, result: Computed<unknown>): void;
+/**
+ * Law 7 postcondition for a plain successful value or report. Scalar facades and object-valued
+ * analyses do not have an envelope in which a non-finite number can hide, so they use the same
+ * exhaustive walker as {@link assertFiniteResult}. Aligned arrays are checked by their explained
+ * companion because only its declared `diagnostics.warmup` can distinguish a legitimate prefix
+ * sentinel from a defect.
+ */
+/**
+ * Law 7's INPUT-DRIVEN twin (2026-08-23 review wave): refuse a computed result that finite inputs
+ * pushed past IEEE-754 double precision. `assertFiniteValue` reports a non-finite success as a
+ * LIBRARY defect ("please report it"); this finalizer reports it as the caller's magnitudes
+ * overflowing the arithmetic — a teaching refusal, not a bug report. Every public
+ * facade/analysis/ratified-plain answer in the Stage 4 domain packages returns through one of the
+ * two; the overflow mutant (`tools/first-touch/overflow-sweep.test.ts`) holds the law.
+ */
+export declare function requireRepresentableResult<T>(functionName: string, result: T): T;
+/**
+ * Sum signed finite addends without losing a representable answer to evaluation order.
+ *
+ * The ordinary path uses a non-overlapping floating-point expansion: low-order residuals survive
+ * cancellation (`1e16 + 1 − 1e16 === 1`). If one partial addition itself overflows, the fallback
+ * decodes each double into an exact BigInt superaccumulator and rounds the exact total once. That
+ * fallback is what makes `1e308 + 1e308 + 1 − 1e308 − 1e308` return `1` in every permutation while
+ * still returning Infinity when the mathematical sum of the supplied doubles exceeds
+ * `Number.MAX_VALUE`. Non-finite addends retain ordinary IEEE-754 propagation semantics.
+ */
+export declare function stableSum(addends: readonly number[]): number;
+export declare function assertFiniteValue(label: string, value: unknown): void;
+/** Validate and return a direct Computed result in one expression. */
+export declare function finalizeResult<Result extends Computed<unknown>>(label: string, result: Result): Result;
+/**
+ * A callable `(input) => Output` with an `.explain(input) => Computed<Output, Extra>` companion. The
+ * `Extra` type parameter carries the domain-specific assumptions the envelope discloses (it defaults
+ * to none), so `f.explain(input).assumptions.<extraField>` type-checks.
+ */
+/**
+ * `ExplainValue` defaults to `Output` and diverges only for solver facades (Law 7 / E3): the plain
+ * call THROWS on failure so its output stays `number`, while the `.explain` envelope reports the
+ * same failure softly as `value: null` + `converged: false`.
+ */
+export type Facade<Input, Output, Extra extends Record<string, unknown> = Record<never, never>, ExplainValue = Output> = ((input: Input) => Output) & {
+    explain: (input: Input) => Computed<ExplainValue, Extra>;
+};
+/**
+ * Pair a plain-value `call` with its envelope-returning `explain` into a single {@link Facade}.
+ * `label` is the public name of the facade as the user calls it (e.g. `'blackScholes.call'`) — it opens every
+ * guard message. S1 facades take an input OBJECT of named fields, so arrays are rejected here too.
+ */
+export declare function facade<Input, Output, Extra extends Record<string, unknown> = Record<never, never>, ExplainValue = Output>(label: string, call: (input: Input) => Output, explain: (input: Input) => Computed<ExplainValue, Extra>): Facade<Input, Output, Extra, ExplainValue>;
+/**
+ * A multi-argument (series-first) facade: the plain call takes `(data, parameters?, …)`, and `.explain()`
+ * takes the SAME arguments and returns the {@link Computed} envelope. This is the S2 shape (`rsi(closes,
+ * parameters?)`, `sharpe(returns, options?)`) — distinct from {@link Facade}, which is the single-object S1
+ * shape (`blackScholes.call({ … })`).
+ */
+export type SeriesFacade<Args extends unknown[], Output, Extra extends Record<string, unknown> = Record<never, never>> = ((...callArguments: Args) => Output) & {
+    explain: (...callArguments: Args) => Computed<Output, Extra>;
+};
+/**
+ * Pair a series-first `call` with an `.explain()` that takes the same arguments (S2 facades).
+ * `label` is the public name of the facade as the user calls it (e.g. `'sharpe'`).
+ */
+export declare function seriesFacade<Args extends unknown[], Output, Extra extends Record<string, unknown> = Record<never, never>>(label: string, call: (...callArguments: Args) => Output, explain: (...callArguments: Args) => Computed<Output, Extra>): SeriesFacade<Args, Output, Extra>;
+//# sourceMappingURL=facade.d.ts.map

package/modules/core/dist/facade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facade.d.ts","sourceRoot":"","sources":["../src/facade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAiD9C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,IAAI,CAejF;AAED;;;;;;GAMG;AACH;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAQhF;AAkDD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAuC5D;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAUrE;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,MAAM,SAAS,QAAQ,CAAC,OAAO,CAAC,EAC7D,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,MAAM,CAGR;AAmGD;;;;GAIG;AACH;;;;GAIG;AACH,MAAM,MAAM,MAAM,CAChB,KAAK,EACL,MAAM,EACN,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAC5D,YAAY,GAAG,MAAM,IACnB,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC,GAAG;IAC/B,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,QAAQ,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;CAC1D,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,MAAM,CACpB,KAAK,EACL,MAAM,EACN,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAC5D,YAAY,GAAG,MAAM,EAErB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,EAC9B,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,QAAQ,CAAC,YAAY,EAAE,KAAK,CAAC,GACvD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,CAc5C;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,CACtB,IAAI,SAAS,OAAO,EAAE,EACtB,MAAM,EACN,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAC1D,CAAC,CAAC,GAAG,aAAa,EAAE,IAAI,KAAK,MAAM,CAAC,GAAG;IACzC,OAAO,EAAE,CAAC,GAAG,aAAa,EAAE,IAAI,KAAK,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC9D,CAAC;AAEF;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,SAAS,OAAO,EAAE,EACtB,MAAM,EACN,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAE5D,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,CAAC,GAAG,aAAa,EAAE,IAAI,KAAK,MAAM,EACxC,OAAO,EAAE,CAAC,GAAG,aAAa,EAAE,IAAI,KAAK,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,GAC3D,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,CAoBnC"}