@actuarial-ts/core 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,280 @@
+/**
+ * Core domain types for the reserving engine.
+ *
+ * Triangle semantics (ground truth for the whole engine):
+ * - rows = origin periods, columns = development ages
+ * - cells not yet observable are null
+ * - every computation must be null-safe; division by a missing, zero, or
+ *   negative denominator yields "no factor" (null), never an exception or NaN
+ */
+/** Cadence of origin periods. */
+export type OriginCadence = "annual" | "quarterly";
+/** The kinds of triangles the engine knows how to build and analyze. */
+export type TriangleKind = "paid" | "incurred" | "caseReserve" | "reportedCount" | "openCount" | "closedCount" | "closedWithPayCount";
+export interface Triangle {
+    kind: TriangleKind;
+    /** Human-readable origin period labels, ascending (e.g. "2019", "2021Q3"). */
+    origins: string[];
+    /** Development ages in months, ascending (e.g. [12, 24, 36] or [3, 6, 9]). */
+    ages: number[];
+    /** values[originIndex][ageIndex]; null = not yet observable / missing. */
+    values: (number | null)[][];
+}
+/** A single claim evaluation snapshot: one row per claim per evaluation date. */
+export interface ClaimSnapshot {
+    claimId: string;
+    /** ISO date (yyyy-mm-dd) the loss occurred. */
+    accidentDate: string;
+    /** ISO date the claim was reported to the insurer. */
+    reportDate: string;
+    /** ISO date this snapshot was evaluated. */
+    evaluationDate: string;
+    /** Cumulative paid loss as of the evaluation date. */
+    paidToDate: number;
+    /** Outstanding case reserve as of the evaluation date. */
+    caseReserve: number;
+    /** Claim status as of the evaluation date. */
+    status: "open" | "closed";
+}
+/**
+ * Exposure data by origin period. A period may carry earned premium (the base
+ * for the loss-ratio method), exposure units (the base for the pure-premium
+ * method), or both. The reserving methods are base-agnostic: the caller feeds
+ * whichever base the chosen method uses into `earnedPremium`.
+ */
+export interface ExposureRecord {
+    /** Origin period label matching triangle origins (e.g. "2021" or "2021Q3"). */
+    origin: string;
+    /** Earned premium for the period (the loss-ratio base); null if not imported. */
+    earnedPremium: number | null;
+    /** Exposure units for the period (the pure-premium base); null if not imported. */
+    exposureUnits: number | null;
+}
+/** How a link-ratio average is computed for a development column. */
+/**
+ * Keys of the standard averages menu (DEFAULT_AVERAGES). Custom AverageSpec
+ * keys remain legal; these are the ones every exhibit and consumer can rely
+ * on being present.
+ */
+export declare const AVERAGE_KEYS: readonly ["all-wtd", "all-str", "5-wtd", "5-str", "3-wtd", "3-str", "med-5x1", "geo-all"];
+export type AverageKey = (typeof AVERAGE_KEYS)[number];
+export interface AverageSpec {
+    /** One of AVERAGE_KEYS for the standard menu; custom keys are permitted. */
+    key: AverageKey | (string & {});
+    label: string;
+    kind: "straight" | "weighted" | "medial" | "geometric";
+    /** Number of most recent origin periods to include; omit for all-year. */
+    years?: number;
+}
+/** Age-to-age factors for one triangle. */
+export interface DevelopmentFactors {
+    /** For column j: development from ages[j] to ages[j+1]. Length = ages.length - 1. */
+    fromAges: number[];
+    toAges: number[];
+    /** individual[originIndex][columnIndex]; null where not computable. */
+    individual: (number | null)[][];
+    /** Per-average-key, per-column computed averages; null where not computable. */
+    averages: {
+        spec: AverageSpec;
+        values: (number | null)[];
+    }[];
+}
+/** Per-column LDF selection made by the user or the advisor. */
+export interface LdfSelections {
+    /** selected[j] = LDF for development column j; null = not selected. */
+    selected: (number | null)[];
+    tailFactor: number;
+}
+export interface ChainLadderRow {
+    origin: string;
+    /** Age (months) of the latest observed diagonal cell for this origin. */
+    latestAge: number;
+    /** Value on the latest observed diagonal. */
+    latestValue: number;
+    /** Cumulative development factor from latestAge to ultimate. */
+    cdf: number;
+    percentDeveloped: number;
+    ultimate: number;
+    /** ultimate - latestValue (IBNR on incurred basis; unpaid on paid basis). */
+    unpaid: number;
+}
+export interface ChainLadderResult {
+    method: "chainLadder";
+    basis: TriangleKind;
+    /** cdfs[j] = cumulative factor from ages[j] to ultimate (last = tail factor). */
+    cdfs: number[];
+    percentDeveloped: number[];
+    rows: ChainLadderRow[];
+    totals: {
+        latest: number;
+        ultimate: number;
+        unpaid: number;
+    };
+    warnings: string[];
+}
+export interface BornhuetterFergusonRow {
+    origin: string;
+    latestValue: number;
+    cdf: number;
+    /** A-priori expected loss ratio applied to the exposure base. */
+    aprioriLossRatio: number;
+    earnedPremium: number;
+    expectedUltimate: number;
+    expectedUnreported: number;
+    ultimate: number;
+    unpaid: number;
+}
+export interface BornhuetterFergusonResult {
+    method: "bornhuetterFerguson";
+    basis: TriangleKind;
+    rows: BornhuetterFergusonRow[];
+    totals: {
+        latest: number;
+        ultimate: number;
+        unpaid: number;
+    };
+    warnings: string[];
+}
+export type TailMethod = "exponentialDecay" | "inversePower";
+export interface TailFit {
+    method: TailMethod;
+    /** ln(f-1) = intercept + slope * x, x = period index (exp) or ln(index) (power). */
+    intercept: number;
+    slope: number;
+    rSquared: number;
+    nPoints: number;
+    /** Individual extrapolated age-to-age factors beyond the last observed age. */
+    extrapolatedFactors: number[];
+    tailFactor: number;
+    valid: boolean;
+    warnings: string[];
+}
+export interface MackRow {
+    origin: string;
+    latest: number;
+    ultimate: number;
+    reserve: number;
+    standardError: number;
+    /** standardError / reserve; null when reserve is 0. */
+    cv: number | null;
+}
+export interface MackResult {
+    method: "mack";
+    /** The projection factors: selected LDFs when supplied, else volume-weighted. */
+    developmentFactors: number[];
+    sigmaSquared: number[];
+    /** Tail factor the projection used (1 = none). */
+    tailFactor?: number;
+    /** Extrapolated sigma^2 for the tail step; present only when a tail was applied. */
+    sigmaSquaredTail?: number;
+    rows: MackRow[];
+    totals: {
+        latest: number;
+        ultimate: number;
+        reserve: number;
+        standardError: number;
+        cv: number | null;
+    };
+    warnings: string[];
+}
+export interface MerzWuthrichRow {
+    origin: string;
+    /** Chain ladder reserve at time I (ultimate minus the latest diagonal). */
+    reserve: number;
+    /**
+     * sqrt of the one-year CDR msep (Merz-Wuthrich 2008, eq. 3.17): the
+     * prediction uncertainty of 0 for next year's observable claims
+     * development result - the Solvency II / SST one-year reserve risk.
+     */
+    cdrMsepRoot: number;
+    /** sqrt of Mack's full-runoff msep for the same origin (ultimate view). */
+    mackMsepRoot: number;
+    /** cdrMsepRoot / mackMsepRoot; null when the Mack msep is 0. */
+    oneYearRatio: number | null;
+}
+export interface MerzWuthrichResult {
+    method: "merzWuthrich";
+    /** Volume-weighted development factors fhat_j estimated at time I. */
+    developmentFactors: number[];
+    /** sigma^2_j estimates; the final column uses Mack's extrapolation (4.1). */
+    sigmaSquared: number[];
+    rows: MerzWuthrichRow[];
+    totals: {
+        reserve: number;
+        /** Aggregate one-year msep root per eq. (3.18), cross terms included. */
+        cdrMsepRoot: number;
+        /** Mack's total full-runoff msep root, cross terms included. */
+        mackMsepRoot: number;
+        /** totals.cdrMsepRoot / totals.mackMsepRoot; null when the Mack total is 0. */
+        oneYearRatio: number | null;
+    };
+    warnings: string[];
+}
+export interface BerquistCaseAdequacyResult {
+    /** Average open case reserve per open claim, by cell. */
+    averageCaseReserves: (number | null)[][];
+    /** Annual severity trend used to restate historical average case reserves. */
+    severityTrend: number;
+    /** Whether the trend was fitted from the data or supplied by the user. */
+    trendSource: "fitted" | "user";
+    restatedAverageCaseReserves: (number | null)[][];
+    /** paid + restated average case reserve x open counts. */
+    adjustedIncurred: Triangle;
+    warnings: string[];
+}
+export interface BerquistSettlementResult {
+    /** disposal[i][j] = closed counts / ultimate counts for origin i. */
+    disposalRates: (number | null)[][];
+    /** Selected disposal rate per age (latest diagonal). */
+    selectedDisposalRates: (number | null)[];
+    ultimateCounts: number[];
+    adjustedClosedCounts: (number | null)[][];
+    interpolation: "exponential" | "linear";
+    adjustedPaid: Triangle;
+    warnings: string[];
+}
+export interface CalendarYearDiagnostic {
+    /** One entry per calendar-period diagonal that has testable factors. */
+    diagonals: {
+        label: string;
+        countLarge: number;
+        countSmall: number;
+        z: number;
+        expectedZ: number;
+        varianceZ: number;
+    }[];
+    totalZ: number;
+    expectedTotalZ: number;
+    varianceTotalZ: number;
+    /** Total Z outside the 95% confidence range indicates calendar-year effects. */
+    significant: boolean;
+    confidenceInterval: [number, number];
+}
+export interface DiagnosticsResult {
+    paidToIncurredRatios: (number | null)[][];
+    averageCaseReserves: (number | null)[][];
+    /** closed / reported counts by cell. */
+    closureRates: (number | null)[][];
+    calendarYearTest: CalendarYearDiagnostic | null;
+    /** Human-readable findings an actuary would care about. */
+    findings: DiagnosticFinding[];
+}
+export interface DiagnosticFinding {
+    severity: "info" | "warning" | "critical";
+    code: string;
+    message: string;
+}
+/**
+ * Every machine-readable code a ReservingError can carry. This registry is
+ * public contract: consumers may switch exhaustively on ReservingErrorCode,
+ * and test/registry.test.ts enforces that the list matches every constructor
+ * site in source. Add the code here when introducing a new throw.
+ */
+export declare const RESERVING_ERROR_CODES: readonly ["BAD_ADJ", "BAD_CAP", "BAD_CASHFLOWS", "BAD_CDF", "BAD_COUNTS", "BAD_DATE", "BAD_ELR", "BAD_FIT", "BAD_LIMIT", "BAD_LOSSES", "BAD_MARGIN", "BAD_ORIGIN", "BAD_PERCENTILE", "BAD_PREMIUM", "BAD_RATE", "BAD_RATE_CHANGE", "BAD_RATIO", "BAD_SEED", "BAD_SHAPE", "BAD_TABLE", "BAD_TAIL", "BAD_TREND", "BAD_WEIGHTS", "INFINITE_MEAN", "NO_APRIORI", "NO_BF_ROWS", "NO_CLAIMS", "NO_DATA", "NO_DEVELOPMENT", "NO_FACTOR", "NO_PROVENANCE", "NO_SELECTIONS", "SELECTION_SHAPE", "SHAPE", "TABLE_RANGE", "TOO_SMALL"];
+export type ReservingErrorCode = (typeof RESERVING_ERROR_CODES)[number];
+/** Thrown for invalid analysis input (all-missing selections, shape mismatches). */
+export declare class ReservingError extends Error {
+    readonly code: ReservingErrorCode;
+    constructor(code: ReservingErrorCode, message: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,79 @@
+/**
+ * Core domain types for the reserving engine.
+ *
+ * Triangle semantics (ground truth for the whole engine):
+ * - rows = origin periods, columns = development ages
+ * - cells not yet observable are null
+ * - every computation must be null-safe; division by a missing, zero, or
+ *   negative denominator yields "no factor" (null), never an exception or NaN
+ */
+/** How a link-ratio average is computed for a development column. */
+/**
+ * Keys of the standard averages menu (DEFAULT_AVERAGES). Custom AverageSpec
+ * keys remain legal; these are the ones every exhibit and consumer can rely
+ * on being present.
+ */
+export const AVERAGE_KEYS = [
+    "all-wtd",
+    "all-str",
+    "5-wtd",
+    "5-str",
+    "3-wtd",
+    "3-str",
+    "med-5x1",
+    "geo-all",
+];
+/**
+ * Every machine-readable code a ReservingError can carry. This registry is
+ * public contract: consumers may switch exhaustively on ReservingErrorCode,
+ * and test/registry.test.ts enforces that the list matches every constructor
+ * site in source. Add the code here when introducing a new throw.
+ */
+export const RESERVING_ERROR_CODES = [
+    "BAD_ADJ",
+    "BAD_CAP",
+    "BAD_CASHFLOWS",
+    "BAD_CDF",
+    "BAD_COUNTS",
+    "BAD_DATE",
+    "BAD_ELR",
+    "BAD_FIT",
+    "BAD_LIMIT",
+    "BAD_LOSSES",
+    "BAD_MARGIN",
+    "BAD_ORIGIN",
+    "BAD_PERCENTILE",
+    "BAD_PREMIUM",
+    "BAD_RATE",
+    "BAD_RATE_CHANGE",
+    "BAD_RATIO",
+    "BAD_SEED",
+    "BAD_SHAPE",
+    "BAD_TABLE",
+    "BAD_TAIL",
+    "BAD_TREND",
+    "BAD_WEIGHTS",
+    "INFINITE_MEAN",
+    "NO_APRIORI",
+    "NO_BF_ROWS",
+    "NO_CLAIMS",
+    "NO_DATA",
+    "NO_DEVELOPMENT",
+    "NO_FACTOR",
+    "NO_PROVENANCE",
+    "NO_SELECTIONS",
+    "SELECTION_SHAPE",
+    "SHAPE",
+    "TABLE_RANGE",
+    "TOO_SMALL",
+];
+/** Thrown for invalid analysis input (all-missing selections, shape mismatches). */
+export class ReservingError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ReservingError";
+        this.code = code;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAyDH,qEAAqE;AACrE;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,SAAS;IACT,SAAS;IACT,OAAO;IACP,OAAO;IACP,OAAO;IACP,OAAO;IACP,SAAS;IACT,SAAS;CACD,CAAC;AAyNX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,SAAS;IACT,SAAS;IACT,eAAe;IACf,SAAS;IACT,YAAY;IACZ,UAAU;IACV,SAAS;IACT,SAAS;IACT,WAAW;IACX,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,gBAAgB;IAChB,aAAa;IACb,UAAU;IACV,iBAAiB;IACjB,WAAW;IACX,UAAU;IACV,WAAW;IACX,WAAW;IACX,UAAU;IACV,WAAW;IACX,aAAa;IACb,eAAe;IACf,YAAY;IACZ,YAAY;IACZ,WAAW;IACX,SAAS;IACT,gBAAgB;IAChB,WAAW;IACX,eAAe;IACf,eAAe;IACf,iBAAiB;IACjB,OAAO;IACP,aAAa;IACb,WAAW;CACH,CAAC;AAIX,oFAAoF;AACpF,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAqB;IAClC,YAAY,IAAwB,EAAE,OAAe;QACnD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/ulae.d.ts

@@ -0,0 +1,172 @@
+/**
+ * ULAE reserving per Conger & Nolibos (2003), "Estimating ULAE Liabilities:
+ * Rediscovering and Expanding Kittel's Approach" (CAS Forum Fall 2003).
+ *
+ * The generalized framework splits ultimate ULAE into shares spent OPENING
+ * (u1), MAINTAINING (u2) and CLOSING (u3) claims, u1 + u2 + u3 = 1, and
+ * attaches each share to a calendar-period loss measure:
+ *
+ * - u1 <-> R: the ULTIMATE cost of claims REPORTED during the period,
+ * - u2 <-> P: the losses PAID during the period,
+ * - u3 <-> C: the ULTIMATE cost of claims CLOSED during the period.
+ *
+ * Core identity: M = W x B with loss basis B = u1 R + u2 P + u3 C, so the
+ * observed calendar-period ULAE ratio is W = M / B ("losses" always means
+ * losses + ALAE). The actuary reviews W by period, selects W*, and books one
+ * of the paper's three reserve forms (the Bornhuetter-Ferguson form is their
+ * recommended default).
+ *
+ * Special cases (see ULAE_WEIGHT_PRESETS): Kittel's refined method is
+ * u = (50%, 0, 50%) with R = reported and C = paid losses (its no-partial-
+ * payment / no-development assumptions); the classical paid-to-paid method
+ * adds the steady-state identity R = P = C, collapsing the basis to paid
+ * losses alone.
+ *
+ * Validation choices (documented per the phase plan):
+ * - weights must be finite, each within [0, 1], and sum to 1 (1e-6
+ *   tolerance) -> BAD_WEIGHTS;
+ * - monetary amounts (M, R, P, C, L and their to-date counterparts) must be
+ *   finite and non-negative -> BAD_LOSSES;
+ * - the selected ratio W* must be finite and non-negative -> BAD_RATIO;
+ * - a non-positive PER-PERIOD basis yields W = null with a warning (house
+ *   null-safety: division by a non-positive denominator is "no factor",
+ *   never an exception), but a reserve that cannot be formed at all (empty
+ *   periods, missing measures for a positive weight, development form with
+ *   a non-positive basis) throws NO_DATA.
+ */
+export interface UlaeWeights {
+    /** Share of ultimate ULAE spent opening claims (attaches to R). */
+    u1: number;
+    /** Share spent maintaining claims (attaches to paid losses P). */
+    u2: number;
+    /** Share spent closing claims (attaches to C). */
+    u3: number;
+}
+/**
+ * How the calendar-period loss basis is formed:
+ * - "weighted": B = u1 R + u2 P + u3 C (the generalized framework);
+ * - "paid": B = P, the classical method's steady-state simplification
+ *   (R = P = C for a book in steady state, pp. 98-99 of the paper).
+ */
+export type UlaeBasisKind = "weighted" | "paid";
+/**
+ * Weight presets from the paper. The GENERALIZED method is any caller-chosen
+ * triple (there is no handbook of u-values; the paper develops them by
+ * interviewing claims personnel), so it deliberately has no preset entry.
+ */
+export declare const ULAE_WEIGHT_PRESETS: {
+    /**
+     * Kittel's refined method: 50% opening / 50% closing, with the caller
+     * supplying R = reported losses and C = paid losses per Kittel's
+     * assumptions (no partial payments or reopenings, no future development).
+     * W = M / (50% x (paid + reported)).
+     */
+    readonly kittel: {
+        readonly weights: {
+            readonly u1: 0.5;
+            readonly u2: 0;
+            readonly u3: 0.5;
+        };
+        readonly basis: "weighted";
+    };
+    /**
+     * Classical paid-to-paid: the same 50/50 lifecycle assumption plus the
+     * steady-state identity R = P = C, which collapses the basis to paid
+     * losses: W = M / P. Reserve = W* x (IBNR + 50% x case reserves).
+     */
+    readonly classicalPaidToPaid: {
+        readonly weights: {
+            readonly u1: 0.5;
+            readonly u2: 0;
+            readonly u3: 0.5;
+        };
+        readonly basis: "paid";
+    };
+};
+/** One calendar period's inputs (all amounts for the period, not cumulative). */
+export interface UlaePeriodInput {
+    label: string;
+    /** M: ULAE paid during the period. */
+    ulaePaid: number;
+    /** R: ultimate cost of claims reported during the period. */
+    reportedUltimate: number;
+    /** P: losses paid during the period. */
+    paid: number;
+    /** C: ultimate cost of claims closed during the period. */
+    closedUltimate: number;
+}
+export interface UlaeRatioRow {
+    label: string;
+    ulaePaid: number;
+    /** B = u1 R + u2 P + u3 C (or P under the "paid" basis). */
+    basis: number;
+    /** W = M / B; null when the basis is not positive. */
+    ratio: number | null;
+}
+export interface UlaeRatiosResult {
+    weights: UlaeWeights;
+    basis: UlaeBasisKind;
+    rows: UlaeRatioRow[];
+    totals: {
+        ulaePaid: number;
+        basis: number;
+        ratio: number | null;
+    };
+    warnings: string[];
+}
+export type UlaeReserveForm = "expected" | "bornhuetterFerguson" | "development";
+export interface UlaeReserveInput {
+    /** W*: the selected ratio of ultimate ULAE to the loss basis. */
+    selectedW: number;
+    /** L: independently estimated ultimate losses for the reserved group. */
+    ultimateLosses: number;
+    /** R(t): ultimate cost of claims reported as of the evaluation date. Required when u1 > 0. */
+    reportedToDate?: number;
+    /** P(t): losses paid as of the evaluation date. Required when u2 > 0. */
+    paidToDate?: number;
+    /** C(t): ultimate cost of claims closed as of the evaluation date. Required when u3 > 0. */
+    closedToDate?: number;
+    /** M(t): ULAE paid to date. Required for the expected and development forms. */
+    ulaePaidToDate?: number;
+    weights: UlaeWeights;
+    form: UlaeReserveForm;
+}
+export interface UlaeReserveResult {
+    form: UlaeReserveForm;
+    /** The indicated unpaid ULAE. */
+    unpaidUlae: number;
+    /** B(t) = u1 R(t) + u2 P(t) + u3 C(t); null when a needed measure was omitted. */
+    basisToDate: number | null;
+    /**
+     * The Bornhuetter-Ferguson form's split (opening = W* u1 (L - R(t)),
+     * maintaining = W* u2 (L - P(t)), closing = W* u3 (L - C(t))); null for
+     * the other forms.
+     */
+    components: {
+        opening: number;
+        maintaining: number;
+        closing: number;
+    } | null;
+    warnings: string[];
+}
+/**
+ * Calendar-period ULAE ratios W = M / B (the paper's Exhibits B-F machinery).
+ * Pass opts.basis = "paid" for the classical paid-to-paid collapse.
+ */
+export declare function ulaeRatios(periods: UlaePeriodInput[], weights: UlaeWeights, opts?: {
+    basis?: UlaeBasisKind;
+}): UlaeRatiosResult;
+/**
+ * The paper's three reserve forms (pp. 113-115), analogous to expected-loss /
+ * Bornhuetter-Ferguson / development loss reserving:
+ *
+ * - "expected":            unpaid = W* L - M(t)
+ * - "bornhuetterFerguson": unpaid = W* [u1 (L - R(t)) + u2 (L - P(t)) + u3 (L - C(t))]
+ *                          = W* (L - B(t))  -- the paper's recommended default
+ * - "development":         unpaid = M(t) (L / B(t) - 1)
+ *
+ * With Kittel's weights (50/0/50) and C(t) = P(t) the B-F form reduces to
+ * W* x (IBNR + 50% x case reserves) - the Kittel identity.
+ */
+export declare function ulaeReserve(input: UlaeReserveInput): UlaeReserveResult;
+//# sourceMappingURL=ulae.d.ts.map

package/dist/ulae.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ulae.d.ts","sourceRoot":"","sources":["../src/ulae.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,MAAM,WAAW,WAAW;IAC1B,mEAAmE;IACnE,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,MAAM,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;IAC9B;;;;;OAKG;;;;;;;;;IAEH;;;;OAIG;;;;;;;;;CAEK,CAAC;AAEX,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,gBAAgB,EAAE,MAAM,CAAC;IACzB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,WAAW,CAAC;IACrB,KAAK,EAAE,aAAa,CAAC;IACrB,IAAI,EAAE,YAAY,EAAE,CAAC;IACrB,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAClE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,qBAAqB,GAAG,aAAa,CAAC;AAEjF,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,cAAc,EAAE,MAAM,CAAC;IACvB,8FAA8F;IAC9F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4FAA4F;IAC5F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,WAAW,CAAC;IACrB,IAAI,EAAE,eAAe,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,CAAC;IACtB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;;OAIG;IACH,UAAU,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAgCD;;;GAGG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,eAAe,EAAE,EAC1B,OAAO,EAAE,WAAW,EACpB,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,aAAa,CAAA;CAAO,GACnC,gBAAgB,CAsClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,iBAAiB,CA6FtE"}