@insiderfinance/totalfinance 0.1.0

package/modules/core/dist/market-data.js

@@ -0,0 +1,183 @@
+/**
+ * Canonical market-data contracts (spec §7.6). Pure types — plus one tiny quote-price selector and
+ * the ONE `RateCurve` data validator shared by the Gate B snapshot spine and the Gate C pricing
+ * protocol (both consume stored curves as plain data, so both must refuse the same malformations).
+ */
+import { discountFactor, isoDateToEpochMs, yearFraction } from './dates.js';
+import { ErrorCode, InputError } from './errors.js';
+const RATE_CURVE_DAY_COUNTS = ['ACT/365F', 'ACT/360', '30/360'];
+function isValidCompounding(value) {
+    if (value === 'simple' ||
+        value === 'continuous' ||
+        value === 'annual' ||
+        value === 'semiannual' ||
+        value === 'quarterly' ||
+        value === 'monthly')
+        return true;
+    if (value !== null &&
+        typeof value === 'object' &&
+        value.type === 'periodic') {
+        const periods = value.periodsPerYear;
+        return typeof periods === 'number' && Number.isFinite(periods) && periods > 0;
+    }
+    return false;
+}
+function curveError(functionName, message, code, context) {
+    return new InputError(`${functionName}: ${message}`, {
+        code,
+        context: { function: functionName, ...context },
+    });
+}
+/**
+ * The ONE full validator for a stored/observed {@link RateCurve} as PLAIN DATA — shared by the
+ * Gate B market-snapshot spine (`observations.curves`) and the Gate C pricing protocol (the
+ * `discountCurve` observation value), so both refuse the same malformed curves with the same
+ * teaching. Core-internal on purpose: it is validation plumbing, not analysis API.
+ *
+ * Checks: `currency` a non-empty string; `asOf` finite epoch ms; `dayCount`/`compounding` valid
+ * conventions (a curve states its own — no silent economics); `points` an array of AT LEAST ONE
+ * pillar (an empty curve discounts nothing — a consumer handed zero pillars has no discount
+ * function, so emptiness is refused here rather than downstream) whose entries have a REAL
+ * `'YYYY-MM-DD'` calendar date (parsed with core's date parser, so `'2025-02-30'` is refused),
+ * strictly ascending pillar dates, dates at or after the curve's own `asOf` (a pillar BEFORE the
+ * curve's valuation instant discounts into the past — no consumer has a meaning for it; a pillar
+ * exactly AT `asOf` is the legal t = 0 anchor), and a finite `zeroRate` whose discount factor is
+ * actually computable and representable under the curve's compounding at that pillar's tenor;
+ * `interpolation` a non-empty string when present (the declared type). Entries stay open (Law 12):
+ * vendor decoration is preserved, not enumerated here.
+ *
+ * **Pillar authority — `zeroRate` is the ONE datum (2026-08-23, second external review).** The
+ * semantics are the existing fixed-income consumer's: `curves.fromZeroRates(...)` consumes ZERO
+ * RATES quoted under the curve's own `compounding`/`dayCount` and DERIVES every discount factor
+ * through that compounding transform. The former advisory `discountFactor` pillar member is GONE:
+ * a second, potentially contradictory answer must not share a pillar (the old sign-consistency
+ * tolerance accepted `rate: 0.05` beside `discountFactor: 0.2`), and no consumer in the workspace
+ * ever read it — discount-factor-quoted data has its own constructor
+ * (`curves.fromDiscountFactors`), whose pillars carry no rates. What replaced the tolerance is a
+ * REAL economics check through core's own transform (`discountFactor` in `dates.ts` — the one
+ * compounding engine, not a second one): every pillar's derived discount factor must exist and be
+ * a positive finite number, so `zeroRate: -2` under annual compounding (growth factor
+ * `1 + r/m ≤ 0` — no real discount factor exists) and rate/tenor pairs whose factor overflows,
+ * underflows to zero, or goes negative are refused with the arithmetic named.
+ */
+export function requireRateCurveData(functionName, path, value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw curveError(functionName, `${path} must be a RateCurve data object ({ currency, asOf, dayCount, compounding, points }). Received ${value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value}.\n  e.g. { currency: 'USD', asOf: 1784505600000, dayCount: 'ACT/365F', compounding: 'continuous', points: [{ date: '2027-07-20', zeroRate: 0.045 }] }`, ErrorCode.InputWrongType, { field: path });
+    }
+    const curve = value;
+    if (typeof curve.currency !== 'string' || curve.currency.length === 0) {
+        throw curveError(functionName, `${path}.currency must be a currency code string.`, ErrorCode.InputWrongType, { field: `${path}.currency` });
+    }
+    if (typeof curve.asOf !== 'number' || !Number.isFinite(curve.asOf)) {
+        throw curveError(functionName, `${path}.asOf must be finite epoch milliseconds. Received ${typeof curve.asOf === 'number' ? curve.asOf : curve.asOf === null ? 'null' : typeof curve.asOf}.`, typeof curve.asOf === 'number' ? ErrorCode.InputNotFinite : ErrorCode.InputWrongType, { field: `${path}.asOf` });
+    }
+    if (typeof curve.dayCount !== 'string' ||
+        !RATE_CURVE_DAY_COUNTS.includes(curve.dayCount)) {
+        throw curveError(functionName, `${path}.dayCount must be one of ${RATE_CURVE_DAY_COUNTS.join(', ')} — a curve states its own conventions. Received ${JSON.stringify(curve.dayCount)}.`, ErrorCode.InputInvalidEnum, { field: `${path}.dayCount`, value: curve.dayCount });
+    }
+    if (!isValidCompounding(curve.compounding)) {
+        throw curveError(functionName, `${path}.compounding must state the curve's compounding convention: 'simple' | 'continuous' | 'annual' | 'semiannual' | 'quarterly' | 'monthly' or { type: 'periodic', periodsPerYear }.`, ErrorCode.InputInvalidEnum, { field: `${path}.compounding` });
+    }
+    if (!Array.isArray(curve.points)) {
+        throw curveError(functionName, `${path}.points must be an array of { date, zeroRate } pillar points.`, ErrorCode.InputWrongType, { field: `${path}.points` });
+    }
+    if (curve.points.length === 0) {
+        throw curveError(functionName, `${path}.points must contain at least one pillar — an empty curve discounts nothing, and a consumer handed it would have no discount function to evaluate.\n  e.g. points: [{ date: '2027-07-20', zeroRate: 0.045 }]`, ErrorCode.InputOutOfRange, { field: `${path}.points` });
+    }
+    let previousDateMs;
+    let previousDate;
+    for (let i = 0; i < curve.points.length; i++) {
+        const point = curve.points[i];
+        if (point === null || typeof point !== 'object' || Array.isArray(point)) {
+            throw curveError(functionName, `${path}.points[${i}] must be a { date, zeroRate } object.`, ErrorCode.InputWrongType, { field: `${path}.points[${i}]` });
+        }
+        if (typeof point.date !== 'string') {
+            throw curveError(functionName, `${path}.points[${i}].date must be a 'YYYY-MM-DD' string. Received ${point.date === null ? 'null' : typeof point.date}.`, ErrorCode.InputWrongType, { field: `${path}.points[${i}].date` });
+        }
+        let dateMs;
+        try {
+            dateMs = isoDateToEpochMs(point.date);
+        }
+        catch (error) {
+            throw curveError(functionName, `${path}.points[${i}].date is not a real calendar date: ${error instanceof Error ? error.message : String(error)}`, ErrorCode.InputOutOfRange, { field: `${path}.points[${i}].date`, value: point.date });
+        }
+        if (previousDateMs !== undefined && dateMs <= previousDateMs) {
+            throw curveError(functionName, `${path}.points must be strictly ascending by date — points[${i}].date '${point.date}' does not follow points[${i - 1}].date '${previousDate}'. Sort the pillars and remove duplicates.`, ErrorCode.InputOutOfRange, { field: `${path}.points[${i}].date`, previous: previousDate, value: point.date });
+        }
+        previousDateMs = dateMs;
+        previousDate = point.date;
+        // A pillar strictly before the curve's own valuation instant discounts into the past — no
+        // consumer has a meaning for it (2026-08-23, second external review). A pillar exactly AT
+        // asOf is legal: it is the t = 0 anchor, and its discount factor is 1 by construction.
+        if (dateMs < curve.asOf) {
+            throw curveError(functionName, `${path}.points[${i}].date '${point.date}' is before the curve's asOf (${curve.asOf} epoch ms) — a curve discounts FORWARD from its valuation instant, so every pillar must be at or after asOf (a pillar exactly at asOf is the legal t = 0 anchor). Drop the stale pillar or fix asOf.`, ErrorCode.InputOutOfRange, { field: `${path}.points[${i}].date`, value: point.date, asOf: curve.asOf });
+        }
+        if (typeof point.zeroRate !== 'number' || !Number.isFinite(point.zeroRate)) {
+            throw curveError(functionName, `${path}.points[${i}].zeroRate must be a finite decimal zero rate quoted under the curve's own compounding/dayCount (e.g. 0.045 for 4.5%). Received ${typeof point.zeroRate === 'number' ? point.zeroRate : point.zeroRate === null ? 'null' : typeof point.zeroRate}.`, typeof point.zeroRate === 'number' ? ErrorCode.InputNotFinite : ErrorCode.InputWrongType, { field: `${path}.points[${i}].zeroRate` });
+        }
+        // Economic validity: the pillar's discount factor must EXIST under the curve's own conventions
+        // (2026-08-23, second external review — the old advisory-field sign check accepted quotes no
+        // convention can discount). Derived through core's ONE compounding transform, never a second
+        // engine: `discountFactor(zeroRate, t, compounding)` refuses a periodic growth factor
+        // `1 + zeroRate/m ≤ 0` itself, and the result must be a positive finite number — an overflow
+        // to Infinity, an underflow to 0, or a negative factor is a quote nothing downstream can use.
+        const tenorYears = yearFraction(curve.asOf, dateMs, curve.dayCount);
+        let pillarDiscountFactor;
+        try {
+            pillarDiscountFactor = discountFactor(point.zeroRate, tenorYears, curve.compounding);
+        }
+        catch (error) {
+            throw curveError(functionName, `${path}.points[${i}].zeroRate ${point.zeroRate} has no real discount factor under compounding ${JSON.stringify(curve.compounding)}: ${error instanceof Error ? error.message : String(error)}\n  e.g. under 'annual' compounding the zero rate must stay above -1 (-100%), like { date: '${point.date}', zeroRate: -0.02 }.`, ErrorCode.InputOutOfRange, { field: `${path}.points[${i}].zeroRate`, value: point.zeroRate, tenorYears });
+        }
+        if (!Number.isFinite(pillarDiscountFactor) || pillarDiscountFactor <= 0) {
+            throw curveError(functionName, `${path}.points[${i}].zeroRate ${point.zeroRate} yields discount factor ${pillarDiscountFactor} at tenor ${tenorYears} years under compounding ${JSON.stringify(curve.compounding)} — a pillar's discount factor must be a positive finite number, so this quote cannot discount anything. Fix the rate's sign/magnitude or the pillar date.\n  e.g. { date: '${point.date}', zeroRate: 0.045 }.`, ErrorCode.InputOutOfRange, {
+                field: `${path}.points[${i}].zeroRate`,
+                value: point.zeroRate,
+                tenorYears,
+                discountFactor: pillarDiscountFactor,
+            });
+        }
+    }
+    if (curve.interpolation !== undefined &&
+        (typeof curve.interpolation !== 'string' || curve.interpolation.length === 0)) {
+        throw curveError(functionName, `${path}.interpolation must be an interpolation-name string when present (e.g. 'linearZero'). Received ${curve.interpolation === null ? 'null' : typeof curve.interpolation === 'string' ? "''" : typeof curve.interpolation}.`, ErrorCode.InputWrongType, { field: `${path}.interpolation` });
+    }
+    return value;
+}
+/**
+ * Resolve a single price from an option quote per the requested source. Returns `undefined` when
+ * the requested fields are absent. `mid` falls back to (bid+ask)/2 when an explicit mid is missing.
+ * An unknown `source` is a typed error, never a silent `undefined` — "field absent" and "you typed
+ * `'midd'`" must not be the same answer.
+ */
+export function selectQuotePrice(quote, source) {
+    // "Field absent" (undefined) and "field null" are different answers: absent means the venue
+    // did not publish it; null is a wrong-typed value that would flow into (bid+ask)/2 as zero.
+    for (const field of ['bid', 'ask', 'mid', 'last', 'mark']) {
+        const v = quote?.[field];
+        if (v !== undefined && (typeof v !== 'number' || Number.isNaN(v))) {
+            throw new InputError(`selectQuotePrice: quote.${field} must be a number when present. Received ${v === null ? 'null' : typeof v}.`, { code: ErrorCode.InputWrongType, context: { field } });
+        }
+    }
+    switch (source) {
+        case 'bid':
+            return quote.bid;
+        case 'ask':
+            return quote.ask;
+        case 'last':
+            return quote.last;
+        case 'mark':
+            return quote.mark;
+        case 'mid':
+            if (quote.mid !== undefined)
+                return quote.mid;
+            if (quote.bid !== undefined && quote.ask !== undefined)
+                return (quote.bid + quote.ask) / 2;
+            return undefined;
+    }
+    throw new InputError(`selectQuotePrice: source must be one of 'bid', 'ask', 'mid', 'last', 'mark'; got ${JSON.stringify(source)}.`, {
+        code: ErrorCode.InputInvalidEnum,
+        context: { function: 'selectQuotePrice', field: 'source', value: source },
+    });
+}
+//# sourceMappingURL=market-data.js.map

package/modules/core/dist/market-data.js.map

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

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

@@ -0,0 +1,46 @@
+/** Numeric policy and small helpers (spec §7.1). Public analytics use IEEE-754 `number`. */
+/** True only for a real, finite number (rejects `NaN`, `Infinity`, and non-numbers). */
+export declare function isFiniteNumber(value: unknown): value is number;
+export declare function isPositive(value: unknown): value is number;
+export declare function isNonNegative(value: unknown): value is number;
+export interface BetweenOptions {
+    /** Include the bounds (default `true`). */
+    inclusive?: boolean;
+}
+/**
+ * Range predicate. Replaces wrapped-number DSLs (design law #2): use
+ * `between(Math.abs(delta), 0.25, 0.35)` rather than `delta.abs().between(...)`.
+ */
+export declare function between(value: number, min: number, max: number, options?: BetweenOptions): boolean;
+/** Clamp `value` into `[min, max]`. */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Round half-away-from-zero to `decimals` places, robust to floating-point representation.
+ *
+ * Total over the double domain: `decimals` must be an integer in [-323, 323] (10^±323 spans the
+ * whole representable grid — beyond it nothing survives double precision), and the extremes are
+ * exact identities rather than overflow artifacts: an integer input with `decimals >= 0` is
+ * returned unchanged (so `round(1e16, 0)` is 1e16, not 1e16+2, and `round(Number.MAX_VALUE, 2)`
+ * is MAX_VALUE, not Infinity), and when the requested grid is coarser than the value's own ulp the
+ * value is already its rounded self.
+ */
+export declare function round(value: number, decimals?: number): number;
+/** `toFixed` that never throws on non-finite input and never returns `"NaN"` silently. */
+export declare function toFixedSafe(value: number, decimals?: number): string;
+export interface FormatMoneyOptions {
+    currency?: string;
+    locale?: string;
+    decimals?: number;
+}
+/** Format a number as currency using the platform `Intl` (browser-safe). */
+export declare function formatMoney(value: number, options?: FormatMoneyOptions): string;
+export interface FormatPercentOptions {
+    /** Fraction digits (default `2`). */
+    decimals?: number;
+    /** If `true`, the input is already a percentage (e.g. `22`) rather than a fraction (`0.22`). */
+    asPercentagePoints?: boolean;
+    locale?: string;
+}
+/** Format a fraction (`0.22`) as a percent string (`"22.00%"`). */
+export declare function formatPercent(value: number, options?: FormatPercentOptions): string;
+//# sourceMappingURL=numeric.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"numeric.d.ts","sourceRoot":"","sources":["../src/numeric.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAK5F,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE9D;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE1D;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE7D;AAED,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,OAAO,CACrB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAuBT;AAED,uCAAuC;AACvC,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAIrE;AAED;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CA0BzD;AAED,0FAA0F;AAC1F,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAG/D;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,MAAM,CAqCnF;AAED,MAAM,WAAW,oBAAoB;IACnC,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gGAAgG;IAChG,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,MAAM,CAyCvF"}

package/modules/core/dist/numeric.js

@@ -0,0 +1,145 @@
+/** Numeric policy and small helpers (spec §7.1). Public analytics use IEEE-754 `number`. */
+import { ErrorCode, InputError } from './errors.js';
+import { ensureKnownKeys } from './invariants.js';
+/** True only for a real, finite number (rejects `NaN`, `Infinity`, and non-numbers). */
+export function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+export function isPositive(value) {
+    return isFiniteNumber(value) && value > 0;
+}
+export function isNonNegative(value) {
+    return isFiniteNumber(value) && value >= 0;
+}
+/**
+ * Range predicate. Replaces wrapped-number DSLs (design law #2): use
+ * `between(Math.abs(delta), 0.25, 0.35)` rather than `delta.abs().between(...)`.
+ */
+export function between(value, min, max, options = {}) {
+    // Positional front door: between(NaN, 0, 1) used to answer false as if it had CHECKED.
+    for (const [name, v] of [
+        ['value', value],
+        ['min', min],
+        ['max', max],
+    ]) {
+        if (typeof v !== 'number' || Number.isNaN(v)) {
+            throw new InputError(`between: ${name} must be a number — between(0.5, 0, 1). Received ${v === null ? 'null' : v === undefined ? 'undefined' : typeof v === 'number' ? String(v) : typeof v}.`, { code: ErrorCode.InputWrongType, context: { field: name } });
+        }
+    }
+    ensureKnownKeys('between', 'options', options, ['inclusive']);
+    if (options.inclusive !== undefined && typeof options.inclusive !== 'boolean') {
+        throw new InputError(`between: inclusive must be a boolean when provided. Received ${options.inclusive === null ? 'null' : typeof options.inclusive}.`, { code: ErrorCode.InputWrongType, context: { field: 'inclusive' } });
+    }
+    const inclusive = options.inclusive ?? true;
+    return inclusive ? value >= min && value <= max : value > min && value < max;
+}
+/** Clamp `value` into `[min, max]`. */
+export function clamp(value, min, max) {
+    if (value < min)
+        return min;
+    if (value > max)
+        return max;
+    return value;
+}
+/**
+ * Round half-away-from-zero to `decimals` places, robust to floating-point representation.
+ *
+ * Total over the double domain: `decimals` must be an integer in [-323, 323] (10^±323 spans the
+ * whole representable grid — beyond it nothing survives double precision), and the extremes are
+ * exact identities rather than overflow artifacts: an integer input with `decimals >= 0` is
+ * returned unchanged (so `round(1e16, 0)` is 1e16, not 1e16+2, and `round(Number.MAX_VALUE, 2)`
+ * is MAX_VALUE, not Infinity), and when the requested grid is coarser than the value's own ulp the
+ * value is already its rounded self.
+ */
+export function round(value, decimals = 0) {
+    if (!Number.isInteger(decimals) || decimals < -323 || decimals > 323) {
+        throw new InputError(`round: decimals must be an integer in [-323, 323] (the double-precision grid). Received ${String(decimals)}.`, { code: ErrorCode.InputOutOfRange, context: { field: 'decimals', value: decimals } });
+    }
+    if (!Number.isFinite(value))
+        return value;
+    // An integer is a fixed point of rounding to >= 0 decimals. This also sidesteps two failure
+    // modes of scale-and-round: the epsilon nudge corrupting integers at/near 2^53 (where one ulp
+    // is a whole unit), and MAX_VALUE * (1 + ε) overflowing to Infinity.
+    if (decimals >= 0 && Number.isInteger(value))
+        return value;
+    const factor = 10 ** decimals;
+    // The epsilon nudge corrects cases like round(1.005, 2) where the stored double sits a hair
+    // below the true half. It must scale WITH the value (relative, not absolute) so portfolio-sized
+    // numbers like round(1234567.005, 2) get the same correction as values near 1.
+    // Multiplying by (1 + ε) grows the MAGNITUDE for either sign (more positive / more negative),
+    // which is what half-away-from-zero needs on both sides of the axis.
+    let nudged = value * (1 + Number.EPSILON);
+    if (!Number.isFinite(nudged))
+        nudged = value; // the nudge overflowed — fall back to un-nudged
+    const scaled = nudged * factor;
+    // Scaled past 2^53 — or clean over/underflow, which `10 ** ±309…323` reaches on its own — means
+    // every double in reach is already an integer on the requested grid, so rounding is the
+    // identity: return the EXACT input rather than a round-tripped approximation.
+    if (!Number.isFinite(scaled) || Math.abs(scaled) >= 2 ** 53)
+        return value;
+    return Math.round(scaled) / factor;
+}
+/** `toFixed` that never throws on non-finite input and never returns `"NaN"` silently. */
+export function toFixedSafe(value, decimals = 2) {
+    if (!Number.isFinite(value))
+        return Number.isNaN(value) ? 'NaN' : value > 0 ? '∞' : '-∞';
+    return value.toFixed(decimals);
+}
+/** Format a number as currency using the platform `Intl` (browser-safe). */
+export function formatMoney(value, options = {}) {
+    // A formatter fed garbage must teach, never render "$NaN" into a report.
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new InputError(`formatMoney: value must be a finite number — formatMoney(1234.5). Received ${value === null ? 'null' : value === undefined ? 'undefined' : typeof value === 'number' ? String(value) : typeof value}.`, { code: ErrorCode.InputWrongType, context: { field: 'value' } });
+    }
+    ensureKnownKeys('formatMoney', 'options', options, ['currency', 'locale', 'decimals']);
+    for (const field of ['currency', 'locale']) {
+        const v = options[field];
+        if (v !== undefined && typeof v !== 'string') {
+            throw new InputError(`formatMoney: ${field} must be a string when provided. Received ${v === null ? 'null' : typeof v}.`, { code: ErrorCode.InputWrongType, context: { field } });
+        }
+    }
+    if (options.decimals !== undefined &&
+        (typeof options.decimals !== 'number' || !Number.isFinite(options.decimals))) {
+        throw new InputError(`formatMoney: decimals must be a finite number when provided. Received ${options.decimals === null ? 'null' : typeof options.decimals}.`, { code: ErrorCode.InputWrongType, context: { field: 'decimals' } });
+    }
+    const currency = options.currency ?? 'USD';
+    const locale = options.locale ?? 'en-US';
+    const fmt = new Intl.NumberFormat(locale, {
+        style: 'currency',
+        currency,
+        ...(options.decimals !== undefined
+            ? { minimumFractionDigits: options.decimals, maximumFractionDigits: options.decimals }
+            : {}),
+    });
+    return fmt.format(value);
+}
+/** Format a fraction (`0.22`) as a percent string (`"22.00%"`). */
+export function formatPercent(value, options = {}) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new InputError(`formatPercent: value must be a finite number — formatPercent(0.0425). Received ${value === null ? 'null' : value === undefined ? 'undefined' : typeof value === 'number' ? String(value) : typeof value}.`, { code: ErrorCode.InputWrongType, context: { field: 'value' } });
+    }
+    ensureKnownKeys('formatPercent', 'options', options, [
+        'decimals',
+        'asPercentagePoints',
+        'locale',
+    ]);
+    if (options.decimals !== undefined &&
+        (typeof options.decimals !== 'number' || !Number.isFinite(options.decimals))) {
+        throw new InputError(`formatPercent: decimals must be a finite number when provided. Received ${options.decimals === null ? 'null' : typeof options.decimals}.`, { code: ErrorCode.InputWrongType, context: { field: 'decimals' } });
+    }
+    if (options.locale !== undefined && typeof options.locale !== 'string') {
+        throw new InputError(`formatPercent: locale must be a string when provided. Received ${options.locale === null ? 'null' : typeof options.locale}.`, { code: ErrorCode.InputWrongType, context: { field: 'locale' } });
+    }
+    if (options.asPercentagePoints !== undefined && typeof options.asPercentagePoints !== 'boolean') {
+        throw new InputError(`formatPercent: asPercentagePoints must be a boolean when provided — a truthy string must never rescale the value. Received ${options.asPercentagePoints === null ? 'null' : typeof options.asPercentagePoints}.`, { code: ErrorCode.InputWrongType, context: { field: 'asPercentagePoints' } });
+    }
+    const decimals = options.decimals ?? 2;
+    const locale = options.locale ?? 'en-US';
+    const fraction = options.asPercentagePoints ? value / 100 : value;
+    return new Intl.NumberFormat(locale, {
+        style: 'percent',
+        minimumFractionDigits: decimals,
+        maximumFractionDigits: decimals,
+    }).format(fraction);
+}
+//# sourceMappingURL=numeric.js.map

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

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

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

@@ -0,0 +1,28 @@
+/**
+ * One order vocabulary (pre-publish interface repairs, B6).
+ *
+ * Every package that names an order — the portfolio trade lifecycle, the backtest simulators and
+ * the paper broker, the agent wire — spells side, type and time-in-force with THESE names. An
+ * order carries a side and a positive quantity; held exposure is signed; `sideOf` / `signOf` are
+ * the one bridge between the two, so no engine hand-rolls `quantity > 0 ? 'buy' : 'sell'` again.
+ *
+ * Identity rule, written down: market data is keyed by `symbol` (a bar, a quote, a chain row);
+ * ledger and trade objects are keyed by `instrumentId` (a fill, an order, a position). A symbol
+ * is what a venue quotes; an instrument id is what a book holds — the two coincide for a share
+ * and differ for a derivative, so neither name is reused for the other.
+ */
+export type OrderSide = 'buy' | 'sell';
+/** Kebab-case everywhere; a simulator that supports a subset says so at its door. */
+export type OrderType = 'market' | 'limit' | 'stop' | 'stop-limit' | 'market-on-open' | 'market-on-close';
+export type TimeInForce = 'day' | 'gtc';
+export declare const ORDER_SIDES: readonly OrderSide[];
+export declare const ORDER_TYPES: readonly OrderType[];
+export declare const TIME_IN_FORCE_VALUES: readonly TimeInForce[];
+/**
+ * The side of a signed quantity: positive buys, negative sells. Zero and non-finite values have
+ * no side and are refused — a caller that reaches here with `0` has a sizing bug, not an order.
+ */
+export declare function sideOf(signed: number, functionName?: string): OrderSide;
+/** The sign of a side: `+1` for a buy, `-1` for a sell. Any other value is refused. */
+export declare function signOf(side: OrderSide, functionName?: string): 1 | -1;
+//# sourceMappingURL=orders.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"orders.d.ts","sourceRoot":"","sources":["../src/orders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,CAAC;AAEvC,qFAAqF;AACrF,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,OAAO,GACP,MAAM,GACN,YAAY,GACZ,gBAAgB,GAChB,iBAAiB,CAAC;AAEtB,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,KAAK,CAAC;AAExC,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAAmC,CAAC;AAChF,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAO1C,CAAC;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,WAAW,EAAkC,CAAC;AAE1F;;;GAGG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,SAAW,GAAG,SAAS,CAazE;AAED,uFAAuF;AACvF,wBAAgB,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,YAAY,SAAW,GAAG,CAAC,GAAG,CAAC,CAAC,CAUvE"}

package/modules/core/dist/orders.js

@@ -0,0 +1,49 @@
+/**
+ * One order vocabulary (pre-publish interface repairs, B6).
+ *
+ * Every package that names an order — the portfolio trade lifecycle, the backtest simulators and
+ * the paper broker, the agent wire — spells side, type and time-in-force with THESE names. An
+ * order carries a side and a positive quantity; held exposure is signed; `sideOf` / `signOf` are
+ * the one bridge between the two, so no engine hand-rolls `quantity > 0 ? 'buy' : 'sell'` again.
+ *
+ * Identity rule, written down: market data is keyed by `symbol` (a bar, a quote, a chain row);
+ * ledger and trade objects are keyed by `instrumentId` (a fill, an order, a position). A symbol
+ * is what a venue quotes; an instrument id is what a book holds — the two coincide for a share
+ * and differ for a derivative, so neither name is reused for the other.
+ */
+import { ErrorCode, InputError } from './errors.js';
+export const ORDER_SIDES = Object.freeze(['buy', 'sell']);
+export const ORDER_TYPES = Object.freeze([
+    'market',
+    'limit',
+    'stop',
+    'stop-limit',
+    'market-on-open',
+    'market-on-close',
+]);
+export const TIME_IN_FORCE_VALUES = Object.freeze(['day', 'gtc']);
+/**
+ * The side of a signed quantity: positive buys, negative sells. Zero and non-finite values have
+ * no side and are refused — a caller that reaches here with `0` has a sizing bug, not an order.
+ */
+export function sideOf(signed, functionName = 'sideOf') {
+    if (typeof signed !== 'number' || !Number.isFinite(signed) || signed === 0) {
+        throw new InputError(`${functionName}: a side needs a non-zero finite signed quantity (positive buys, negative sells). Received ${typeof signed === 'number' ? String(signed) : typeof signed}.`, {
+            code: signed === 0 ? ErrorCode.InputOutOfRange : ErrorCode.InputWrongType,
+            context: { function: functionName, field: 'signed', value: signed },
+        });
+    }
+    return signed > 0 ? 'buy' : 'sell';
+}
+/** The sign of a side: `+1` for a buy, `-1` for a sell. Any other value is refused. */
+export function signOf(side, functionName = 'signOf') {
+    if (side === 'buy')
+        return 1;
+    if (side === 'sell')
+        return -1;
+    throw new InputError(`${functionName}: side must be 'buy' | 'sell'. Received ${JSON.stringify(side)}.`, {
+        code: ErrorCode.InputInvalidEnum,
+        context: { function: functionName, field: 'side', value: side },
+    });
+}
+//# sourceMappingURL=orders.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"orders.js","sourceRoot":"","sources":["../src/orders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAepD,MAAM,CAAC,MAAM,WAAW,GAAyB,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;AAChF,MAAM,CAAC,MAAM,WAAW,GAAyB,MAAM,CAAC,MAAM,CAAC;IAC7D,QAAQ;IACR,OAAO;IACP,MAAM;IACN,YAAY;IACZ,gBAAgB;IAChB,iBAAiB;CAClB,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA2B,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AAE1F;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,MAAc,EAAE,YAAY,GAAG,QAAQ;IAC5D,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,UAAU,CAClB,GAAG,YAAY,8FACb,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,MACvD,GAAG,EACH;YACE,IAAI,EAAE,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,cAAc;YACzE,OAAO,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE;SACpE,CACF,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;AACrC,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,MAAM,CAAC,IAAe,EAAE,YAAY,GAAG,QAAQ;IAC7D,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,CAAC,CAAC;IAC7B,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,CAAC,CAAC,CAAC;IAC/B,MAAM,IAAI,UAAU,CAClB,GAAG,YAAY,2CAA2C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EACjF;QACE,IAAI,EAAE,SAAS,CAAC,gBAAgB;QAChC,OAAO,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE;KAChE,CACF,CAAC;AACJ,CAAC"}