@insiderfinance/totalfinance 0.1.0

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

@@ -0,0 +1,31 @@
+/** The rich result envelope returned by every pro API (spec §5.2). */
+import type { Assumptions } from './assumptions.js';
+import type { Diagnostics } from './diagnostics.js';
+import type { Provenance } from './provenance.js';
+export interface Computed<T, Extra extends Record<string, unknown> = Record<never, never>> {
+    /**
+     * The computed value. Never `NaN` or `±Infinity`: a value the model cannot produce is `null`
+     * beside a diagnostic that says why (Law 7 — a warning never licenses a non-finite number).
+     */
+    value: T;
+    /** Every applied convention, echoed back. */
+    assumptions: Assumptions<Extra>;
+    /** How the value was computed, plus any warnings. */
+    diagnostics: Diagnostics;
+    /** Optional data lineage when the inputs came from a provider. */
+    provenance?: Provenance;
+}
+/**
+ * C (hygiene): the one question a caller asks of any envelope — may I act on this number? A result
+ * is trustworthy when its iterative procedure converged (or none ran: `converged` absent) and no
+ * warning is an error. `converged` lives on `diagnostics` everywhere; a result that also reports it
+ * in its value mirrors the diagnostics slot, so this reads one place.
+ */
+export declare function isTrustworthy(result: unknown): boolean;
+/**
+ * Runtime guard for the one-envelope law (dx §7.2): a rich result is `Computed` iff it carries
+ * `value`, `assumptions.conventionsVersion`, and a `diagnostics.warnings` array. Exported so
+ * generic result handlers (and the conformance sweep in CI) can assert the shape.
+ */
+export declare function isComputed(value: unknown): value is Computed<unknown>;
+//# sourceMappingURL=computed.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"computed.d.ts","sourceRoot":"","sources":["../src/computed.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,WAAW,QAAQ,CAAC,CAAC,EAAE,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC;IACvF;;;OAGG;IACH,KAAK,EAAE,CAAC,CAAC;IACT,6CAA6C;IAC7C,WAAW,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC;IAChC,qDAAqD;IACrD,WAAW,EAAE,WAAW,CAAC;IACzB,kEAAkE;IAClE,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAatD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAAC,OAAO,CAAC,CAQrE"}

package/modules/core/dist/computed.js

@@ -0,0 +1,40 @@
+/** The rich result envelope returned by every pro API (spec §5.2). */
+/**
+ * C (hygiene): the one question a caller asks of any envelope — may I act on this number? A result
+ * is trustworthy when its iterative procedure converged (or none ran: `converged` absent) and no
+ * warning is an error. `converged` lives on `diagnostics` everywhere; a result that also reports it
+ * in its value mirrors the diagnostics slot, so this reads one place.
+ */
+export function isTrustworthy(result) {
+    // A predicate over an arbitrary value (like `isComputed`): anything that is not an envelope with
+    // a diagnostics record is not trustworthy, and never a thrown error.
+    if (result === null || typeof result !== 'object')
+        return false;
+    const diagnostics = result.diagnostics;
+    if (diagnostics === null || typeof diagnostics !== 'object')
+        return false;
+    const { converged, warnings } = diagnostics;
+    if (converged === false)
+        return false;
+    if (!Array.isArray(warnings))
+        return false;
+    return !warnings.some((w) => w !== null && typeof w === 'object' && w.severity === 'error');
+}
+/**
+ * Runtime guard for the one-envelope law (dx §7.2): a rich result is `Computed` iff it carries
+ * `value`, `assumptions.conventionsVersion`, and a `diagnostics.warnings` array. Exported so
+ * generic result handlers (and the conformance sweep in CI) can assert the shape.
+ */
+export function isComputed(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const v = value;
+    if (!('value' in v))
+        return false;
+    const a = v.assumptions;
+    if (a === null || typeof a !== 'object' || typeof a.conventionsVersion !== 'string')
+        return false;
+    const d = v.diagnostics;
+    return d !== null && typeof d === 'object' && Array.isArray(d.warnings);
+}
+//# sourceMappingURL=computed.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"computed.js","sourceRoot":"","sources":["../src/computed.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAoBtE;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,MAAe;IAC3C,iGAAiG;IACjG,qEAAqE;IACrE,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAChE,MAAM,WAAW,GAAI,MAAoC,CAAC,WAAW,CAAC;IACtE,IAAI,WAAW,KAAK,IAAI,IAAI,OAAO,WAAW,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC1E,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,WAA0D,CAAC;IAC3F,IAAI,SAAS,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IACtC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3C,OAAO,CAAC,QAAQ,CAAC,IAAI,CACnB,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAK,CAA4B,CAAC,QAAQ,KAAK,OAAO,CAC5F,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,KAA0E,CAAC;IACrF,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAClC,MAAM,CAAC,GAAG,CAAC,CAAC,WAA2D,CAAC;IACxE,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,kBAAkB,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAClG,MAAM,CAAC,GAAG,CAAC,CAAC,WAAiD,CAAC;IAC9D,OAAO,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;AAC1E,CAAC"}

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

@@ -0,0 +1,59 @@
+/**
+ * Canonical option contract types (spec §7.6).
+ *
+ * These are pure types (zero runtime cost). `@insiderfinance/totalfinance/options` re-exports them and adds pricing
+ * market types, builders, and engines. Quotes/trades/dividends and the rest of the market-data
+ * contracts live in `market-data.ts`.
+ */
+import type { EpochMs } from './time.js';
+export type OptionType = 'call' | 'put';
+/**
+ * Exercise style of a LISTED equity/index option. `'bermudan'` was removed (alignment spec P3.4):
+ * no vanilla engine supports it, and a representable-but-unpriceable state violates
+ * valid-by-construction. Bermudan RATES exercise lives where it is actually priced —
+ * `@insiderfinance/totalfinance/fixed-income`'s `bermudanSwaption` with its explicit exercise-date schedule.
+ */
+export type OptionStyle = 'european' | 'american';
+export type Settlement = 'physical' | 'cash';
+export type ExerciseTime = 'AM' | 'PM';
+export interface Deliverable {
+    cash?: number;
+    shares?: Array<{
+        symbol: string;
+        quantity: number;
+    }>;
+    notes?: string;
+}
+export interface OptionContract {
+    underlying: string;
+    type: OptionType;
+    /** REQUIRED at build — never defaulted: US equity options are American, many index options European. */
+    style: OptionStyle;
+    strike: number;
+    /** The expiry LABEL as supplied: `YYYY-MM-DD` (a calendar date) or a zoned ISO datetime. */
+    expiry: string;
+    /**
+     * The exact expiration INSTANT the label resolved to (epoch ms), stamped by the builders at
+     * construction: a bare date resolves via the named `expiryConvention`; a zoned datetime is the
+     * caller's explicit instant. REQUIRED (E2, one expiry law): engines price against this
+     * resolution and cross-validate it against the label — an unresolved literal is not a
+     * contract; build one with the option builders.
+     */
+    expiresAt: EpochMs;
+    /** HOW `expiry` resolved to `expiresAt` — named, never silent (spec P1.6/P3.4). */
+    expiryConvention: 'us-equity-close' | 'explicit-instant';
+    multiplier?: number;
+    settlement?: Settlement;
+    /**
+     * AM- or PM-settled — settlement/display metadata. It does NOT move `expiresAt`: the expiry
+     * instant always comes from the `expiry` label and `expiryConvention`. Express an AM-settled
+     * index expiry as a zoned datetime (`'2026-09-18T09:30:00-04:00'`) when its instant matters.
+     */
+    exerciseTime?: ExerciseTime;
+    currency?: string;
+    root?: string;
+    occSymbol?: string;
+    deliverable?: Deliverable;
+    adjusted?: boolean;
+}
+//# sourceMappingURL=contracts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,CAAC;AACxC;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,UAAU,CAAC;AAClD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;AAC7C,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,IAAI,CAAC;AAEvC,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAE7B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,UAAU,CAAC;IACjB,wGAAwG;IACxG,KAAK,EAAE,WAAW,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB,mFAAmF;IACnF,gBAAgB,EAAE,iBAAiB,GAAG,kBAAkB,CAAC;IAIzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;;OAIG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}

package/modules/core/dist/contracts.js

@@ -0,0 +1,9 @@
+/**
+ * Canonical option contract types (spec §7.6).
+ *
+ * These are pure types (zero runtime cost). `@insiderfinance/totalfinance/options` re-exports them and adds pricing
+ * market types, builders, and engines. Quotes/trades/dividends and the rest of the market-data
+ * contracts live in `market-data.ts`.
+ */
+export {};
+//# sourceMappingURL=contracts.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

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

@@ -0,0 +1,31 @@
+/**
+ * Date, day-count, and compounding helpers (spec §7.2, §7.4).
+ *
+ * These operate on explicit inputs only — ISO date strings or epoch milliseconds — and never read
+ * the system clock (design law #5). 30/360 needs calendar components, so date-based day counts
+ * accept either an ISO date or an epoch (converted via UTC).
+ */
+import type { InterestCompounding, DayCount, EpochMs } from './time.js';
+export interface CalendarDate {
+    year: number;
+    month: number;
+    day: number;
+}
+/** Parse an ISO `YYYY-MM-DD` date into calendar components, validating it is a real date. */
+export declare function parseIsoDate(value: string): CalendarDate;
+/** Convert an ISO `YYYY-MM-DD` date to epoch milliseconds at UTC midnight. */
+export declare function isoDateToEpochMs(value: string): EpochMs;
+/**
+ * Year fraction between two dates under a day-count convention.
+ *
+ * - `ACT/365F` and `ACT/360` use actual elapsed days.
+ * - `30/360` uses the US (NASD) bond-basis adjustment on calendar components.
+ */
+export declare function yearFraction(from: string | EpochMs, to: string | EpochMs, dayCount?: DayCount): number;
+/** Periods per year for a discrete convention; `null` for the two non-discrete forms. */
+export declare function compoundingPeriodsPerYear(compounding: InterestCompounding): number | null;
+/** Discount factor for `rate` over `years` under any {@link InterestCompounding} form. */
+export declare function discountFactor(annualRate: number, years: number, compounding?: InterestCompounding): number;
+/** Compound (growth) factor for `rate` over `years` under any {@link InterestCompounding} form. */
+export declare function compoundFactor(annualRate: number, years: number, compounding?: InterestCompounding): number;
+//# sourceMappingURL=dates.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dates.d.ts","sourceRoot":"","sources":["../src/dates.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIxE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,6FAA6F;AAC7F,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CA2BxD;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAMvD;AAYD;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,GAAG,OAAO,EACtB,EAAE,EAAE,MAAM,GAAG,OAAO,EACpB,QAAQ,GAAE,QAAqB,GAC9B,MAAM,CAYR;AAED,yFAAyF;AACzF,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,mBAAmB,GAAG,MAAM,GAAG,IAAI,CA+BzF;AAYD,0FAA0F;AAC1F,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,WAAW,GAAE,mBAAkC,GAC9C,MAAM,CAOR;AAED,mGAAmG;AACnG,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,WAAW,GAAE,mBAAkC,GAC9C,MAAM,CAOR"}

package/modules/core/dist/dates.js

@@ -0,0 +1,126 @@
+/**
+ * Date, day-count, and compounding helpers (spec §7.2, §7.4).
+ *
+ * These operate on explicit inputs only — ISO date strings or epoch milliseconds — and never read
+ * the system clock (design law #5). 30/360 needs calendar components, so date-based day counts
+ * accept either an ISO date or an epoch (converted via UTC).
+ */
+import { ErrorCode, InputError } from './errors.js';
+const MS_PER_DAY = 86_400_000;
+/** Parse an ISO `YYYY-MM-DD` date into calendar components, validating it is a real date. */
+export function parseIsoDate(value) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+    if (!m) {
+        throw new InputError(`parseIsoDate: Invalid ISO date "${value}" (expected YYYY-MM-DD).`, {
+            code: ErrorCode.InputWrongType,
+            context: { field: 'date', value },
+        });
+    }
+    const year = Number(m[1]);
+    const month = Number(m[2]);
+    const day = Number(m[3]);
+    // Probe via setUTCFullYear, NOT `new Date(Date.UTC(...))`: Date.UTC remaps years 0–99 to
+    // 1900–1999 (the legacy two-digit convention), which made every 0000–0099 date — leap or not —
+    // misreport as "not a valid calendar date".
+    const probe = new Date(0);
+    probe.setUTCFullYear(year, month - 1, day);
+    if (probe.getUTCFullYear() !== year ||
+        probe.getUTCMonth() !== month - 1 ||
+        probe.getUTCDate() !== day) {
+        throw new InputError(`parseIsoDate: "${value}" is not a valid calendar date.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { field: 'date', value },
+        });
+    }
+    return { year, month, day };
+}
+/** Convert an ISO `YYYY-MM-DD` date to epoch milliseconds at UTC midnight. */
+export function isoDateToEpochMs(value) {
+    const { year, month, day } = parseIsoDate(value);
+    // Same two-digit-year hazard as the parse probe: build the epoch with the literal year.
+    const d = new Date(0);
+    d.setUTCFullYear(year, month - 1, day);
+    return d.getTime();
+}
+function toCalendarDate(input) {
+    if (typeof input === 'string')
+        return parseIsoDate(input);
+    const d = new Date(input);
+    return { year: d.getUTCFullYear(), month: d.getUTCMonth() + 1, day: d.getUTCDate() };
+}
+function toMs(input) {
+    return typeof input === 'string' ? isoDateToEpochMs(input) : input;
+}
+/**
+ * Year fraction between two dates under a day-count convention.
+ *
+ * - `ACT/365F` and `ACT/360` use actual elapsed days.
+ * - `30/360` uses the US (NASD) bond-basis adjustment on calendar components.
+ */
+export function yearFraction(from, to, dayCount = 'ACT/365F') {
+    if (dayCount === '30/360') {
+        const a = toCalendarDate(from);
+        const b = toCalendarDate(to);
+        let d1 = a.day;
+        let d2 = b.day;
+        if (d1 === 31)
+            d1 = 30;
+        if (d2 === 31 && d1 === 30)
+            d2 = 30;
+        return (360 * (b.year - a.year) + 30 * (b.month - a.month) + (d2 - d1)) / 360;
+    }
+    const days = (toMs(to) - toMs(from)) / MS_PER_DAY;
+    return dayCount === 'ACT/360' ? days / 360 : days / 365;
+}
+/** Periods per year for a discrete convention; `null` for the two non-discrete forms. */
+export function compoundingPeriodsPerYear(compounding) {
+    if (typeof compounding === 'object') {
+        if (!Number.isFinite(compounding.periodsPerYear) || compounding.periodsPerYear <= 0) {
+            throw new InputError(`compounding.periodsPerYear must be a finite number > 0. Received ${String(compounding.periodsPerYear)}.`, { code: ErrorCode.InputOutOfRange, context: { field: 'periodsPerYear' } });
+        }
+        return compounding.periodsPerYear;
+    }
+    switch (compounding) {
+        case 'continuous':
+        case 'simple':
+            return null;
+        case 'annual':
+            return 1;
+        case 'semiannual':
+            return 2;
+        case 'quarterly':
+            return 4;
+        case 'monthly':
+            return 12;
+        default:
+            throw new InputError(`compoundingPeriodsPerYear: Unknown compounding "${String(compounding)}".`, {
+                code: ErrorCode.InputInvalidEnum,
+                context: { field: 'compounding', value: compounding },
+            });
+    }
+}
+/** A periodic rate at or below −100% has no real growth factor: `(1 + r/m) ≤ 0` (FC0 domain law). */
+function requirePeriodicRateAboveFloor(annualRate, periodsPerYear) {
+    if (annualRate / periodsPerYear <= -1) {
+        throw new InputError(`requirePeriodicRateAboveFloor: annualRate ${annualRate} is at or below −100% per period for periodsPerYear ${periodsPerYear} — the growth factor (1 + r/m) is not positive.`, { code: ErrorCode.InputOutOfRange, context: { field: 'annualRate', value: annualRate } });
+    }
+}
+/** Discount factor for `rate` over `years` under any {@link InterestCompounding} form. */
+export function discountFactor(annualRate, years, compounding = 'continuous') {
+    const periods = compoundingPeriodsPerYear(compounding);
+    if (periods === null) {
+        return compounding === 'simple' ? 1 / (1 + annualRate * years) : Math.exp(-annualRate * years);
+    }
+    requirePeriodicRateAboveFloor(annualRate, periods);
+    return Math.pow(1 + annualRate / periods, -periods * years);
+}
+/** Compound (growth) factor for `rate` over `years` under any {@link InterestCompounding} form. */
+export function compoundFactor(annualRate, years, compounding = 'continuous') {
+    const periods = compoundingPeriodsPerYear(compounding);
+    if (periods === null) {
+        return compounding === 'simple' ? 1 + annualRate * years : Math.exp(annualRate * years);
+    }
+    requirePeriodicRateAboveFloor(annualRate, periods);
+    return Math.pow(1 + annualRate / periods, periods * years);
+}
+//# sourceMappingURL=dates.js.map

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

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

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

@@ -0,0 +1,278 @@
+/** Diagnostics and warnings carried by every pro-API result (spec §5.2). */
+import type { SelectionReport } from './pricing.js';
+export type WarningSeverity = 'info' | 'warn' | 'error';
+/** A structured, machine-readable warning. `code` is stable public API. */
+export interface QuantWarning {
+    code: string;
+    message: string;
+    severity: WarningSeverity;
+    context?: Record<string, unknown>;
+}
+/** Non-value metadata about how a result was computed. */
+export interface Diagnostics {
+    /** Pricing/solver engine name, e.g. `black-scholes-merton`. */
+    engine?: string;
+    /** Numerical method, e.g. `closed-form`, `brent`, `finite-difference`. */
+    method?: string;
+    /** Whether an iterative procedure converged. `false` means the value is not trustworthy. */
+    converged?: boolean;
+    /** Iteration count for iterative methods. */
+    iterations?: number;
+    /**
+     * When a meta-engine (e.g. `engines.auto()`) selected a delegate, this is a one-sentence,
+     * human-readable explanation of WHY that delegate was chosen (`engine` then names the delegate).
+     * Absent when no auto-selection took place.
+     */
+    autoReason?: string;
+    /**
+     * The structured engine-selection report (Gate C, `@insiderfinance/totalfinance/core/pricing`): who was selected,
+     * why, and — for automatic selection — every candidate considered with its verdict. This is the
+     * machine-readable superset of `engine` + `autoReason` (which remain for compatibility);
+     * `selected.name` always agrees with `engine` when both are present.
+     */
+    selection?: SelectionReport;
+    /**
+     * Named intermediate quantities the value decomposes into — a par spread's protection leg and
+     * risky annuity, a forward variance's near/far legs. The H-series explain paths disclose their
+     * arithmetic here so a caller can audit the ratio, not just receive it (3B.3).
+     */
+    decomposition?: Record<string, number>;
+    /** Structured warnings; always present (possibly empty). */
+    warnings: QuantWarning[];
+    /** Wall-clock timing in milliseconds, when measured. */
+    timingMs?: number;
+    /**
+     * Series facades: number of leading output slots that are warmup sentinels (null/NaN) while the
+     * computation seeds. Equals the input length when the indicator never emitted.
+     */
+    warmup?: number;
+    /**
+     * Finite-difference engines: the ACTUAL bump sizes used for FD Greeks (spec P2.3) — adaptive
+     * near the vol/time boundaries, so the caller can see exactly what was differenced.
+     * Keys: `spotStep`, `volatilityStep`, `timeStepYears`, `rateStep`, and — extended Greeks only —
+     * `dividendYieldStep`. Each is the actual step differenced, in the unit of the coordinate it
+     * bumps. (This doc named the retired `hS`/`hSig`/`hT`/`hR`/`hQ` keys for one release after the
+     * emit sites had moved to the semantic names, so a caller following it read `undefined`.)
+     */
+    finiteDifferenceBumps?: Record<string, number>;
+}
+/** Construct an empty diagnostics object with no warnings. */
+export declare function emptyDiagnostics(): Diagnostics;
+/** Build a warning helper, defaulting severity to `warn`. */
+export declare function warning(code: string, message: string, severity?: WarningSeverity, context?: Record<string, unknown>): QuantWarning;
+/**
+ * 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 declare const WarningCode: {
+    readonly DataLockedMarket: "data.locked_market";
+    readonly DataZeroBidAsk: "data.zero_bid_ask";
+    readonly SurfaceExtrapolated: "volatility.surface_extrapolated";
+    readonly BinomialStepsRoundedOdd: "binomial.steps_rounded_odd";
+    readonly GreeksNotComputed: "greeks.not_computed";
+    readonly SuspiciousVolatility: "input.suspicious_volatility";
+    readonly SuspiciousTime: "input.suspicious_time";
+    readonly SuspiciousRiskFreeRate: "input.suspicious_risk_free_rate";
+    readonly SuspiciousReturns: "input.suspicious_returns";
+    /** The result is NaN/degenerate BY DESIGN (empty series, zero variance) — disclosed, not fabricated. */
+    readonly DegenerateInput: "input.degenerate";
+    /** Elasticity Λ = Δ·S/V is undefined (price underflowed to 0) — reported as `null`, never NaN/∞. */
+    readonly LambdaUndefined: "greeks.lambda_undefined";
+    /** Fractional compounding of a ≤−100%-per-interval rate is undefined — reported as `null`, never NaN. */
+    readonly CompoundingUndefined: "crypto.compounding_undefined";
+    /** Compounded annualization exceeded IEEE-754 range — reported as `null`, never Infinity. */
+    readonly CompoundingOverflow: "crypto.compounding_overflow";
+    /** A degenerate/collinear covariance was eigenvalue-floored to keep the SPD postcondition. */
+    readonly CovarianceFloored: "math.covariance_floored";
+    /** Greeks were explicitly requested but this engine cannot compute them — request not honored. */
+    readonly GreeksUnsupportedByEngine: "greeks.unsupported_by_engine";
+    /** A structural limitation of the model/data the caller should know about (design law #4). */
+    readonly ModelLimitation: "model.limitation";
+    /** A valid reusable FX quote was supplied but no target required it in this scenario run. */
+    readonly ScenarioUnusedCurrencyConversion: "scenario.unused_currency_conversion";
+    readonly BacktestAssignment: "backtest.assignment";
+    readonly BacktestDataDuplicateTimestamp: "backtest.data_duplicate_timestamp";
+    readonly BacktestDataNonfinite: "backtest.data_nonfinite";
+    /** Stage 4.6 (FC8): a benchmark session had no return and counted as 0; the count rides the warning. */
+    readonly BacktestDataMissing: "backtest.data_missing";
+    /** Stage 4.6 (FC8) — a pre-trade limit rejected an entry (the row names the limit and the values). */
+    readonly BacktestLimitRejected: "backtest.limit_rejected";
+    /** Stage 4.6 (FC8) — a structure could not fill every leg under the fill policy (the row names the legs). */
+    readonly BacktestComboLegUnfilled: "backtest.combo_leg_unfilled";
+    /** Stage 4.6 (FC8) — maintenance margin breached under forcedLiquidation 'none'. */
+    readonly BacktestMarginBreach: "backtest.margin_breach";
+    /** Stage 4.6 (FC8) — a forced close under the declared liquidation policy (the row names the position and the shortfall). */
+    readonly BacktestForcedLiquidation: "backtest.forced_liquidation";
+    readonly BacktestDataUnsorted: "backtest.data_unsorted";
+    readonly 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. */
+    readonly BacktestMarkFallback: "backtest.mark_fallback";
+    readonly BacktestLookahead: "backtest.lookahead";
+    readonly BacktestMarginRejected: "backtest.margin_rejected";
+    readonly BacktestMarkedAtCost: "backtest.marked_at_cost";
+    readonly BacktestNegativeCash: "backtest.negative_cash";
+    readonly BacktestShortRejected: "backtest.short_rejected";
+    readonly BacktestSignalWarmup: "backtest.signal_warmup";
+    readonly CryptoCarryArbitrage: "crypto.carry_arbitrage";
+    readonly CryptoExtremeFunding: "crypto.extreme_funding";
+    readonly EstimateRiskNeutral: "estimate.risk_neutral";
+    readonly FlowSweepsNotVenueVerified: "flow.sweeps_not_venue_verified";
+    readonly HestonCosineExpansionUnstable: "heston.cosine_expansion_unstable";
+    readonly HestonFellerViolated: "heston.feller_violated";
+    readonly ImpliedVolatilityBracketExpanded: "implied_volatility.bracket_expanded";
+    readonly ImpliedVolatilityFlatHistory: "implied_volatility.flat_history";
+    readonly ImpliedVolatilityLowVega: "implied_volatility.low_vega";
+    readonly LookbackZeroCarry: "lookback.zero_carry";
+    readonly MathCovarianceEwmaEffectiveSample: "math.covariance_ewma_effective_sample";
+    readonly MathCovarianceIllConditioned: "math.covariance_ill_conditioned";
+    readonly MathCovarianceMethodAuto: "math.covariance_method_auto";
+    readonly MathCovarianceSingular: "math.covariance_singular";
+    readonly MonteCarloQuasiMonteCarloDimensionFallback: "monte_carlo.quasi_monte_carlo_dimension_fallback";
+    readonly OptimizeNotConverged: "optimize.not_converged";
+    /** A library result reported this warning as a bare sentence; the envelope carries it typed. */
+    readonly OperationUntypedWarning: "operation.untyped_warning";
+    readonly OptionsDividendsNone: "options.dividends_none";
+    readonly OptionsDividendsPast: "options.dividends_past";
+    readonly OptionsExerciseDiscreteDividends: "options.exercise_discrete_dividends";
+    /** Quote-only chain health was requested; model bounds and implied volatility are not assessed. */
+    readonly OptionsChainHealthModelNotRequested: "options.chain_health.model_not_requested";
+    readonly PerformanceSuspiciousEquityInput: "performance.suspicious_equity_input";
+    readonly PerformanceNonFiniteMetric: "performance.non_finite_metric";
+    /** `analyze` on a series with zero return periods: every metric is null (E3 degenerate summary). */
+    readonly PerformanceEmptySeries: "performance.empty_series";
+    /** Zero gross exposure: concentration metrics are undefined and reported as null. */
+    readonly RiskZeroGrossExposure: "risk.zero_gross_exposure";
+    /** `compareEngines`: one or more engines failed to price (per-row detail on the failed rows). */
+    readonly OptionsEngineFailed: "options.engine_failed";
+    /** `openingRange`: fewer bars than `periods` — the range covers the whole series. */
+    readonly TechnicalAnalysisOpeningRangeTruncated: "technical_analysis.opening_range_truncated";
+    /** `unusualness`: flat baseline — the z-score is undefined and reported null. */
+    readonly StructureFlatBaseline: "structure.flat_baseline";
+    /** Surface/model calibration finished without meeting tolerance — best-effort parameters returned. */
+    readonly VolatilityCalibrationNotConverged: "volatility.calibration_not_converged";
+    readonly PerformanceUndefinedMetric: "performance.undefined_metric";
+    readonly ResearchSurvivorshipBias: "research.survivorship_bias";
+    readonly ResearchTrainTestLeakage: "research.train_test_leakage";
+    /** `probabilityOfBacktestOverfitting`: the oldest rows were trimmed so T divides into S blocks. */
+    readonly ResearchBacktestOverfittingProbabilityTrimmed: "research.backtest_overfitting_probability_trimmed";
+    readonly RiskBrinsonWeights: "risk.brinson_weights";
+    readonly RiskCornishFisherConditionalValueAtRiskGaussianFallback: "risk.cornish_fisher_conditional_value_at_risk_gaussian_fallback";
+    readonly RiskCornishFisherOutOfDomain: "risk.cornish_fisher_out_of_domain";
+    readonly 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. */
+    readonly RiskAsOfUnscreened: "risk.as_of_unscreened";
+    /** A frontier point with zero volatility has no Sharpe ratio (reported null with the reason). */
+    readonly 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. */
+    readonly RiskFrontierUnboundedReturn: "risk.frontier_unbounded_return";
+    /** Solved frontier points are not monotone in volatility versus expected return. */
+    readonly RiskFrontierNotMonotone: "risk.frontier_not_monotone";
+    /** One or more requested frontier points could not be solved (kept with their reasons). */
+    readonly RiskFrontierPointsFailed: "risk.frontier_points_failed";
+    readonly RiskExtremeValueConfidenceOutsideTail: "risk.extreme_value_confidence_outside_tail";
+    readonly RiskExtremeValueDegenerateFit: "risk.extreme_value_degenerate_fit";
+    readonly RiskExtremeValueFewExceedances: "risk.extreme_value_few_exceedances";
+    readonly RiskExtremeValueInfiniteMean: "risk.extreme_value_infinite_mean";
+    readonly RiskExtremeValueInfiniteVariance: "risk.extreme_value_infinite_variance";
+    readonly RiskExtremeValueMleFallback: "risk.extreme_value_mle_fallback";
+    readonly RiskHighCostDrag: "risk.high_cost_drag";
+    readonly RiskInfeasibleConstraints: "risk.infeasible_constraints";
+    readonly RiskInfeasibleTangency: "risk.infeasible_tangency";
+    readonly RiskKellyEstimationNoEdge: "risk.kelly_estimation_no_edge";
+    readonly RiskKellyEstimationThinSample: "risk.kelly_estimation_thin_sample";
+    readonly RiskKellyFatTails: "risk.kelly_fat_tails";
+    readonly RiskKellyNaiveOverbet: "risk.kelly_naive_overbet";
+    readonly RiskKellyNegativeSum: "risk.kelly_negative_sum";
+    readonly RiskKellyNoEdge: "risk.kelly_no_edge";
+    readonly RiskKellyOver: "risk.kelly_over";
+    readonly RiskKellyUnbounded: "risk.kelly_unbounded";
+    readonly RiskMeanExcessNoLinearRegion: "risk.mean_excess_no_linear_region";
+    /** P&L explain: the unexplained residual dominates the total — the greek expansion broke down. */
+    readonly RiskPnlUnexplainedResidual: "risk.pnl_unexplained_residual";
+    /** `optionsMargin`: a net-short call makes the expiration loss unbounded — `maxLoss` is null. */
+    readonly RiskUnboundedLoss: "risk.unbounded_loss";
+    readonly StrategyVolatilityFloored: "strategy.volatility_floored";
+    /** The reward-to-risk ratio is undefined: an unbounded profit or loss, or a zero maximum loss. */
+    readonly StrategyRiskRewardUndefined: "strategy.risk_reward_undefined";
+    /** `optimizeStrategy`: a candidate's capital requirement is zero — `thesisEvPerCapital` is null. */
+    readonly StrategyOptimizerZeroCapital: "strategy.optimizer_zero_capital";
+    readonly StructureAggressorUnavailable: "structure.aggressor_unavailable";
+    readonly StructureContractsSkipped: "structure.contracts_skipped";
+    /** Repeated contract rows remain additive and may count the same open interest more than once. */
+    readonly StructureDuplicateContractQuotes: "structure.duplicate_contract_quotes";
+    /** Every supplied quote was excluded; empty sums must not be read as measured zero exposure. */
+    readonly StructureNoEligibleQuotes: "structure.no_eligible_quotes";
+    readonly VolatilityButterflyArbitrage: "volatility.butterfly_arbitrage";
+    readonly VolatilityEssviButterfly: "volatility.essvi_butterfly";
+    readonly VolatilityEssviCalendar: "volatility.essvi_calendar";
+    readonly VolatilityEssviCalendarData: "volatility.essvi_calendar_data";
+    readonly VolatilityEssviNotConverged: "volatility.essvi_not_converged";
+    readonly VolatilityFitInsufficientData: "volatility.fit_insufficient_data";
+    readonly VolatilityFitUnconverged: "volatility.fit_unconverged";
+    readonly VolatilityShockDegradedToInterpolated: "volatility.shock_degraded_to_interpolated";
+    readonly VolatilityShockFloored: "volatility.shock_floored";
+    readonly VolatilitySkewDeltaExtrapolated: "volatility.skew_delta_extrapolated";
+    readonly VolatilityObservedSkewUnavailable: "volatility.observed_skew_unavailable";
+    readonly VolatilityObservedSkewQuoteExcluded: "volatility.observed_skew_quote_excluded";
+    /** C hygiene — a zero-variance edge has no Kelly fraction: the sizing is null, never an input error. */
+    readonly RiskKellyZeroVariance: "risk.kelly_zero_variance";
+    /** C hygiene — a zero-variance return series has no Sharpe ratio: the statistic is null. */
+    readonly RiskSharpeUndefined: "risk.sharpe_undefined";
+    /** B7 — `chainGreeks` returned some rows unchanged; `diagnostics.rows` names each reason. */
+    readonly OptionsChainGreeksRowsSkipped: "chain_greeks.rows_skipped";
+    readonly VolatilityObservedSkewMissingDelta: "volatility.observed_skew_missing_delta";
+    readonly VolatilityObservedSkewDuplicateContract: "volatility.observed_skew_duplicate_contract";
+    readonly VolatilitySsviButterfly: "volatility.ssvi_butterfly";
+    readonly VolatilitySsviCalendarData: "volatility.ssvi_calendar_data";
+    readonly VolatilitySsviNotConverged: "volatility.ssvi_not_converged";
+    readonly VolatilityStickyIndeterminate: "volatility.sticky_indeterminate";
+    readonly VolatilityStickyWeakFit: "volatility.sticky_weak_fit";
+    readonly VolatilitySurfaceQuotesSkipped: "volatility.surface_quotes_skipped";
+    readonly VolatilitySurfaceSparse: "volatility.surface_sparse";
+    readonly VolatilitySwaptionCubeExtrapolated: "volatility.swaption_cube_extrapolated";
+    readonly 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). */
+    readonly 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). */
+    readonly 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). */
+    readonly 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). */
+    readonly CurveExtrapolated: "curve.extrapolated";
+};
+export type WarningCode = (typeof WarningCode)[keyof typeof WarningCode];
+/**
+ * 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 declare function plausibilityWarnings(inputs: {
+    volatility?: number;
+    timeToExpiryYears?: number;
+    riskFreeRate?: number;
+}): QuantWarning[];
+/**
+ * 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 declare function suspiciousReturnsWarning(returns: ArrayLike<number>): QuantWarning | undefined;
+//# sourceMappingURL=diagnostics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAI5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAExD,2EAA2E;AAC3E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,eAAe,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,4DAA4D;IAC5D,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChD;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,IAAI,WAAW,CAE9C;AAED,6DAA6D;AAC7D,wBAAgB,OAAO,CACrB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,eAAwB,EAClC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,YAAY,CASd;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;IAUtB,wGAAwG;;IAExG,oGAAoG;;IAEpG,yGAAyG;;IAEzG,6FAA6F;;IAE7F,8FAA8F;;IAE9F,kGAAkG;;IAElG,8FAA8F;;IAE9F,6FAA6F;;;;;IAO7F,wGAAwG;;IAExG,sGAAsG;;IAEtG,6GAA6G;;IAE7G,oFAAoF;;IAEpF,6HAA6H;;;;IAI7H;uGACmG;;;;;;;;;;;;;;;;;;;;;;;;IAwBnG,gGAAgG;;;;;IAKhG,mGAAmG;;;;IAInG,oGAAoG;;IAEpG,qFAAqF;;IAErF,iGAAiG;;IAEjG,qFAAqF;;IAErF,iFAAiF;;IAEjF,sGAAsG;;;;;IAKtG,mGAAmG;;;;;;IAQnG;gEAC4D;;IAE5D,iGAAiG;;IAEjG;oFACgF;;IAEhF,oFAAoF;;IAEpF,2FAA2F;;;;;;;;;;;;;;;;;;;;IAoB3F,kGAAkG;;IAElG,iGAAiG;;;IAGjG,kGAAkG;;IAElG,oGAAoG;;;;IAIpG,kGAAkG;;IAElG,gGAAgG;;;;;;;;;;;;;;IAchG,wGAAwG;;IAExG,4FAA4F;;IAE5F,6FAA6F;;;;;;;;;;;;;IAa7F;kGAC8F;;IAE9F;0EACsE;;IAEtE;oFACgF;;IAEhF;iFAC6E;;CAErE,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAEzE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,YAAY,EAAE,CAkEjB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,YAAY,GAAG,SAAS,CAsB7F"}