@insiderfinance/totalfinance 0.1.0

package/modules/options/dist/black-scholes.js

@@ -0,0 +1,334 @@
+/**
+ * `@insiderfinance/totalfinance/options/black-scholes` — the Black–Scholes facade.
+ *
+ * This is a HOT-PATH deep entrypoint (spec §6, §21.5). It imports only the BSM kernel, tiny core
+ * invariants, and `@insiderfinance/totalfinance/math` — never schema machinery or other engines. Public inputs
+ * retain their runtime guards. Whole-entrypoint and used-function budgets are tested separately;
+ * see `docs/bundle-size.md` for current measurements and the supported import patterns.
+ *
+ * Each facade function returns a plain value and throws typed errors on failure. Its `.explain()`
+ * companion returns the rich `{ value, assumptions, diagnostics }` envelope and reports quantitative
+ * failures (non-convergence, below-intrinsic) in `diagnostics` instead of throwing (design law #3).
+ */
+import { ensureFiniteWhenPresent, ErrorCode, WarningCode, ensureEnum, ensureFinite, ensurePositive, plausibilityWarnings, ensureKnownKeys, requireFiniteFields, warning, } from '../../core/dist/index.js';
+import { blackScholesExtendedGreeks, blackScholesGreeks, blackScholesImpliedVolatility, blackScholesPriceUnchecked, } from './bsm.js';
+import { withLambdaDisclosure, withUnderflowDisclosure, analyticAssumptions, facade, impliedVolatilityFacadePair, } from './facade-util.js';
+const MODEL = 'black-scholes-merton';
+const OPTION_TYPES = ['call', 'put'];
+const BSM_KEYS = [
+    'spot',
+    'strike',
+    'timeToExpiryYears',
+    'riskFreeRate',
+    'volatility',
+    'dividendYield',
+];
+const BSM_TYPED_KEYS = [...BSM_KEYS, 'type'];
+const BSM_IV_KEYS = [...BSM_TYPED_KEYS, 'price'];
+/** The numeric legs the facade REQUIRES (`dividendYield` is optional and defaults to 0). */
+const BSM_REQUIRED_NUMERIC = [
+    'spot',
+    'strike',
+    'timeToExpiryYears',
+    'riskFreeRate',
+    'volatility',
+];
+/**
+ * Derived per METHOD, because `validateCore` is shared by five of them.
+ *
+ * One constant naming `blackScholes.price` meant a caller who omitted `volatility` on
+ * `blackScholes.greeks` was shown a call to `.price` — a different method with a different return
+ * type. `.call`/`.put` additionally carry the option type in the METHOD NAME, so an example with a
+ * `type` field is not merely off-target there, it is a call they must not copy.
+ */
+const BSM_MARKET_LEGS = 'spot: 100, strike: 105, timeToExpiryYears: 0.25, riskFreeRate: 0.04, volatility: 0.2';
+function facadeExampleCall(functionName) {
+    // `.call` / `.put` own the convention in their name and reject a `type` key (Law 12).
+    const typed = !/\.(call|put)$/.test(functionName);
+    return `${functionName}({ ${typed ? "type: 'call', " : ''}${BSM_MARKET_LEGS} })`;
+}
+const BSM_FACADE_HINTS = {
+    volatility: 'annualized decimal, not 20',
+    riskFreeRate: 'annualized decimal',
+    timeToExpiryYears: 'in years — 0.25 is three months, not 90',
+};
+function validateCore(input, functionName) {
+    // Law 12: an unknown field (a `divYield` typo, a stray `sigma`) teaches instead of being ignored.
+    ensureKnownKeys(functionName, 'input', input, BSM_TYPED_KEYS);
+    // A meaning-changing field is never coerced (design law #4): `type: 'Call'` must teach, not
+    // silently price the other leg.
+    ensureEnum(input.type, OPTION_TYPES, 'type', functionName);
+    /**
+     * PRESENCE before DOMAIN, and the order is the whole point of the facade/kernel parity fixture.
+     *
+     * `ensurePositive(undefined)` reports `input.not_finite`, because `Number.isFinite(undefined)` is
+     * false — technically true and useless: the caller did not pass a bad number, they passed no
+     * number. The kernel says `input.missing_field` and names the field; the facade said "not finite"
+     * for the same request, so the two layers described one mistake two ways. Presence is checked
+     * first, on the same shared path the kernel uses, and the domain checks below then run on values
+     * that are known to be finite numbers.
+     *
+     * `dividendYield` is deliberately absent here: the facade documents it as optional and defaults it
+     * to 0 just below, which is a real difference from the kernel and not a parity defect.
+     */
+    requireFiniteFields(functionName, input, BSM_REQUIRED_NUMERIC, {
+        exampleCall: () => facadeExampleCall(functionName),
+        hints: BSM_FACADE_HINTS,
+    });
+    ensurePositive(input.spot, 'spot', functionName, ErrorCode.InputNegativeSpot);
+    ensurePositive(input.strike, 'strike', functionName, ErrorCode.InputNegativeStrike);
+    ensurePositive(input.timeToExpiryYears, 'timeToExpiryYears', functionName, ErrorCode.InputNegativeTime);
+    ensurePositive(input.volatility, 'volatility', functionName, ErrorCode.InputNegativeVolatility);
+    ensureFinite(input.riskFreeRate, 'riskFreeRate', functionName);
+    // Null is a wrong-typed value, not omission (the 350c2796 ruling): it used to coalesce
+    // to 0 BEFORE the finite check and silently price a dividend-free underlying.
+    ensureFiniteWhenPresent(input.dividendYield, 'dividendYield', functionName);
+    const q = input.dividendYield ?? 0;
+    return q;
+}
+function assumptions(t, q) {
+    return analyticAssumptions({
+        model: MODEL,
+        timeToExpiryYears: t,
+        dividendModel: q === 0 ? 'none' : 'continuousYield',
+    });
+}
+function closedForm(input) {
+    // `.explain()` surfaces the classic unit footguns (vol as percent, t as day count) as info
+    // warnings — the plain-value path stays silent-and-correct (plain-number law).
+    return {
+        engine: MODEL,
+        method: 'closed-form',
+        converged: true,
+        warnings: input ? plausibilityWarnings(input) : [],
+    };
+}
+function kernelInput(input, dividendYield) {
+    return {
+        type: input.type,
+        spot: input.spot,
+        strike: input.strike,
+        timeToExpiryYears: input.timeToExpiryYears,
+        riskFreeRate: input.riskFreeRate,
+        dividendYield,
+        volatility: input.volatility,
+    };
+}
+// ---- price (call / put / typed) ----
+/**
+ * `validateCore` above is the boundary: Law 12 keys, the `type` enum, presence-and-finiteness of every
+ * numeric leg, then the domain checks. Calling the VALIDATING kernel after that re-ran the whole set a
+ * second time on the flagship path — a regression introduced when the kernel gained its own field
+ * checks, because before that it only checked the container and the enum. One validation, then math.
+ */
+function priceTyped(input, functionName) {
+    const q = validateCore(input, functionName);
+    return blackScholesPriceUnchecked(kernelInput(input, q));
+}
+function explainTyped(input, functionName) {
+    const q = validateCore(input, functionName);
+    const value = blackScholesPriceUnchecked(kernelInput(input, q));
+    return {
+        value,
+        assumptions: assumptions(input.timeToExpiryYears, q),
+        // A price of exactly 0 is an underflow, not a free option — disclose it (Law 4).
+        diagnostics: withUnderflowDisclosure(closedForm({
+            volatility: input.volatility,
+            timeToExpiryYears: input.timeToExpiryYears,
+            riskFreeRate: input.riskFreeRate,
+        }), value),
+    };
+}
+// The type lives in the NAME for blackScholes.call/blackScholes.put — a user-supplied `type` would be silently
+// overridden by the spread, so it is rejected like any unknown key (Law 12).
+const untyped = (input, functionName) => ensureKnownKeys(functionName, 'input', input, BSM_KEYS);
+// These constructors only allocate callable/explain pairs. They do not calculate, validate an
+// input, or invoke the callbacks until used. Expert-only imports may discard the unused pairs.
+const call = /* @__PURE__ */ facade('blackScholes.call', (input) => (untyped(input, 'blackScholes.call'),
+    priceTyped({ ...input, type: 'call' }, 'blackScholes.call')), (input) => (untyped(input, 'blackScholes.call'),
+    explainTyped({ ...input, type: 'call' }, 'blackScholes.call')));
+const put = /* @__PURE__ */ facade('blackScholes.put', (input) => (untyped(input, 'blackScholes.put'),
+    priceTyped({ ...input, type: 'put' }, 'blackScholes.put')), (input) => (untyped(input, 'blackScholes.put'),
+    explainTyped({ ...input, type: 'put' }, 'blackScholes.put')));
+const price = /* @__PURE__ */ facade('blackScholes.price', (input) => priceTyped(input, 'blackScholes.price'), (input) => explainTyped(input, 'blackScholes.price'));
+// ---- greeks ----
+const greeks = /* @__PURE__ */ facade('blackScholes.greeks', (input) => {
+    const q = validateCore(input, 'blackScholes.greeks');
+    return blackScholesGreeks(kernelInput(input, q));
+}, (input) => {
+    const q = validateCore(input, 'blackScholes.greeks');
+    const value = blackScholesGreeks(kernelInput(input, q));
+    return {
+        value,
+        assumptions: assumptions(input.timeToExpiryYears, q),
+        diagnostics: closedForm({
+            volatility: input.volatility,
+            timeToExpiryYears: input.timeToExpiryYears,
+            riskFreeRate: input.riskFreeRate,
+        }),
+    };
+});
+// ---- higher-order greeks ----
+const extendedGreeks = /* @__PURE__ */ facade('blackScholes.extendedGreeks', (input) => {
+    const q = validateCore(input, 'blackScholes.extendedGreeks');
+    return blackScholesExtendedGreeks(kernelInput(input, q));
+}, (input) => {
+    const q = validateCore(input, 'blackScholes.extendedGreeks');
+    const value = blackScholesExtendedGreeks(kernelInput(input, q));
+    return {
+        value,
+        assumptions: assumptions(input.timeToExpiryYears, q),
+        diagnostics: withLambdaDisclosure(closedForm({
+            volatility: input.volatility,
+            timeToExpiryYears: input.timeToExpiryYears,
+            riskFreeRate: input.riskFreeRate,
+        }), value),
+    };
+});
+// ---- implied volatility ----
+//
+// `blackScholes.impliedVolatility` is the lean hot-path facade: it always uses the bracketed Brent solver — the
+// robust universal default that converges whenever a solution exists — and reports `method: 'brent'`.
+// Method selection (`auto`/`newton`/`halley`/`householder` + fallback) lives on the richer paths that
+// don't carry the 8 KB facade budget: the pro `option.impliedVolatility({ contract: contract, market: market, method })` and
+// the standalone `impliedVolatility(input, options)`.
+function validateImpliedVolatility(input) {
+    ensureKnownKeys('blackScholes.impliedVolatility', 'input', input, BSM_IV_KEYS);
+    ensureEnum(input.type, OPTION_TYPES, 'type', 'blackScholes.impliedVolatility');
+    ensurePositive(input.price, 'price', 'blackScholes.impliedVolatility');
+    ensurePositive(input.spot, 'spot', 'blackScholes.impliedVolatility', ErrorCode.InputNegativeSpot);
+    ensurePositive(input.strike, 'strike', 'blackScholes.impliedVolatility', ErrorCode.InputNegativeStrike);
+    ensurePositive(input.timeToExpiryYears, 'timeToExpiryYears', 'blackScholes.impliedVolatility', ErrorCode.InputNegativeTime);
+    ensureFinite(input.riskFreeRate, 'riskFreeRate', 'blackScholes.impliedVolatility');
+    // Null is a wrong-typed value, not omission (the 350c2796 ruling): it used to coalesce
+    // to 0 BEFORE the finite check and silently price a dividend-free underlying.
+    ensureFiniteWhenPresent(input.dividendYield, 'dividendYield', 'blackScholes.impliedVolatility');
+    const q = input.dividendYield ?? 0;
+    return q;
+}
+/**
+ * Ill-conditioning disclosure for a converged inverse (Law 4): vega is `∂price/∂σ`, so when it
+ * collapses toward zero a one-tick price change moves the implied volatility by a lot — the number is
+ * exact for the price given, and nearly meaningless as an estimate. The suite path
+ * (`impliedVolatility(input, options)`) has always said so; the lean facade now says it too, which is
+ * what keeps a recovered σ from a 1e-12 premium from reading like a normal quote.
+ */
+function lowVegaWarnings(input, dividendYield, volatility) {
+    // Greeks report vega per 1% of σ; the conditioning test is on the per-1.00 derivative.
+    const vega = 100 *
+        blackScholesGreeks({
+            type: input.type,
+            spot: input.spot,
+            strike: input.strike,
+            timeToExpiryYears: input.timeToExpiryYears,
+            riskFreeRate: input.riskFreeRate,
+            dividendYield,
+            volatility,
+        }).vega;
+    if (vega >= 1e-4 * input.spot)
+        return [];
+    return [
+        warning(WarningCode.ImpliedVolatilityLowVega, 'vega is near zero; the implied volatility is ill-conditioned', 'warn', { vega }),
+    ];
+}
+function impliedVolatilityExplain(input) {
+    const q = validateImpliedVolatility(input);
+    const res = blackScholesImpliedVolatility({
+        type: input.type,
+        price: input.price,
+        spot: input.spot,
+        strike: input.strike,
+        timeToExpiryYears: input.timeToExpiryYears,
+        riskFreeRate: input.riskFreeRate,
+        dividendYield: q,
+    });
+    const a = assumptions(input.timeToExpiryYears, q);
+    // The IV input has no vol, but the day-count-as-year-fraction footgun still applies to `t` —
+    // `.explain()` surfaces it the same way blackScholes.price.explain does (the plain path stays silent).
+    const suspicious = plausibilityWarnings({
+        timeToExpiryYears: input.timeToExpiryYears,
+        riskFreeRate: input.riskFreeRate,
+    });
+    if (res.converged) {
+        return {
+            value: res.value,
+            assumptions: a,
+            diagnostics: {
+                engine: MODEL,
+                method: 'brent',
+                converged: true,
+                iterations: res.iterations,
+                warnings: [...lowVegaWarnings(input, q, res.value), ...suspicious],
+            },
+        };
+    }
+    const { code, message, severity } = impliedVolatilityFailure(res.reason);
+    return {
+        value: null,
+        assumptions: a,
+        diagnostics: {
+            engine: MODEL,
+            method: 'brent',
+            converged: false,
+            iterations: res.iterations,
+            warnings: [{ code, message, severity }, ...suspicious],
+        },
+    };
+}
+function impliedVolatilityFailure(reason) {
+    switch (reason) {
+        case 'below_intrinsic':
+            return {
+                code: ErrorCode.ImpliedVolatilityBelowIntrinsic,
+                message: 'price is below intrinsic value; no implied volatility exists',
+                severity: 'error',
+            };
+        case 'above_max_bound':
+            return {
+                code: ErrorCode.ImpliedVolatilityAboveMax,
+                message: 'price is at or above the no-arbitrage upper bound (the σ→∞ limit); no implied volatility exists',
+                severity: 'error',
+            };
+        case 'price_below_resolvable':
+            return {
+                code: ErrorCode.ImpliedVolatilityPriceBelowResolvable,
+                message: 'price is below the σ→0 price floor of this model; no implied volatility exists',
+                severity: 'error',
+            };
+        default:
+            return {
+                code: ErrorCode.ImpliedVolatilityNoConvergence,
+                message: 'implied-volatility solver did not converge',
+                severity: 'error',
+            };
+    }
+}
+/**
+ * The Black–Scholes facade namespace. Flat object arguments in, plain values out; `.explain()` on
+ * each function returns the assumptions/diagnostics envelope.
+ *
+ * @example
+ * ```ts
+ * import { blackScholes } from '@insiderfinance/totalfinance/options';
+ *
+ * blackScholes.price({ spot: 100, strike: 105, timeToExpiryYears: 30 / 365, riskFreeRate: 0.045, volatility: 0.22, type: 'call' });
+ * // → 0.898…  (plain number)
+ *
+ * const { value, assumptions, diagnostics } = blackScholes.greeks.explain({
+ *   spot: 100, strike: 105, timeToExpiryYears: 30 / 365, riskFreeRate: 0.045, volatility: 0.22, type: 'call',
+ * });
+ * // value.delta, value.theta (per day), … — with every assumption disclosed
+ * ```
+ */
+export const blackScholes = /* @__PURE__ */ (() => ({
+    call,
+    put,
+    price,
+    greeks,
+    extendedGreeks,
+    impliedVolatility: impliedVolatilityFacadePair('blackScholes.impliedVolatility', impliedVolatilityExplain, [ErrorCode.ImpliedVolatilityBelowIntrinsic, ErrorCode.ImpliedVolatilityAboveMax], 'implied volatility did not converge'),
+}))();
+// The expert kernel surface of this model subpath (P3.3): direct scalar results with required,
+// named financial inputs. Zero added bundle cost — the facade already imports them.
+export { blackScholesPrice, blackScholesGreeks, blackScholesExtendedGreeks, blackScholesImpliedVolatility, blackScholesPriceBounds, } from './bsm.js';
+//# sourceMappingURL=black-scholes.js.map

package/modules/options/dist/black-scholes.js.map

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

package/modules/options/dist/black76.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `@insiderfinance/totalfinance/options/black76` — the Black-76 model for options on forwards/futures (spec §9.3).
+ *
+ * Black-76 prices an option on a forward price `F` with discounting at rate `r`. Greeks are taken
+ * with respect to the forward. Like the BSM facade, each function returns a plain value and throws on
+ * failure; `.explain()` returns the rich envelope.
+ */
+import { type OptionType } from '../../core/dist/index.js';
+import { type Facade } from './facade-util.js';
+import type { ExtendedGreeks, Greeks } from './types.js';
+export interface Black76Input {
+    forward: number;
+    strike: number;
+    timeToExpiryYears: number;
+    riskFreeRate: number;
+    volatility: number;
+}
+export interface Black76TypedInput extends Black76Input {
+    type: OptionType;
+}
+export interface Black76ImpliedVolatilityInput {
+    price: number;
+    forward: number;
+    strike: number;
+    timeToExpiryYears: number;
+    riskFreeRate: number;
+    type: OptionType;
+}
+export type Black76PriceBoundsInput = Omit<Black76TypedInput, 'volatility'>;
+/**
+ * Black-76 price.
+ *
+ * The second seed defect named in the spec, and the same shape as the first: omitting `volatility`
+ * made `sigma` `undefined`, `d1` `NaN`, and the returned price `NaN` — a success-typed wrong number.
+ */
+export declare function black76Price(input: Black76TypedInput): number;
+/** Black-76 first-order Greeks (theta/day, vega/1%, rho/1%; delta/gamma w.r.t. the forward). */
+export declare function black76Greeks(input: Black76TypedInput): Greeks;
+/**
+ * Black-76 higher-order Greeks (w.r.t. the forward `F`). The forward-price derivatives (vanna, charm,
+ * vomma, speed, color, zomma, veta, ultima) coincide with BSM's at `S = F`, `q = r` — Black-76 has the
+ * same `d1`/`d2` and discount as that BSM instance — so they are borrowed from {@link blackScholesExtendedGreeks};
+ * the forward-model-specific ones are computed directly:
+ *   - `vera` = ∂rho/∂σ = ∂(−T·price)/∂σ = −T·vega,
+ *   - `phi`  = 0 (the forward model has no dividend yield; carry is embedded in `F`),
+ *   - `lambda` = Δ·F/V.
+ * First-order fields (theta/rho) come from {@link black76Greeks}, which are the Black-76 conventions.
+ */
+export declare function black76ExtendedGreeks(input: Black76TypedInput): ExtendedGreeks;
+/** No-arbitrage price bounds for Black-76. */
+export declare function black76PriceBounds(input: Black76PriceBoundsInput): {
+    lower: number;
+    upper: number;
+};
+export interface Black76ImpliedVolatilityResult {
+    value: number;
+    converged: boolean;
+    iterations: number;
+    reason?: 'below_intrinsic' | 'above_max_bound' | 'price_below_resolvable' | 'no_bracket' | 'max_iterations';
+}
+/**
+ * Solve Black-76 implied volatility. Reports failure honestly; never fabricates a value. Bounds and
+ * endpoint acceptance follow the same RELATIVE-tolerance rules as the BSM kernel (see
+ * {@link impliedVolatilityPriceTolerance}): a target below the σ→0 price floor fails as
+ * `price_below_resolvable`, and a target at the σ→∞ upper bound as `above_max_bound`.
+ */
+export declare function black76ImpliedVolatility(input: Black76ImpliedVolatilityInput): Black76ImpliedVolatilityResult;
+/** The Black-76 facade namespace. */
+export declare const black76: {
+    call: Facade<Black76Input, number>;
+    put: Facade<Black76Input, number>;
+    price: Facade<Black76TypedInput, number>;
+    greeks: Facade<Black76TypedInput, Greeks>;
+    extendedGreeks: Facade<Black76TypedInput, ExtendedGreeks>;
+    impliedVolatility: Facade<Black76ImpliedVolatilityInput, number, Record<never, never>, number | null>;
+};
+//# sourceMappingURL=black76.d.ts.map

package/modules/options/dist/black76.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"black76.d.ts","sourceRoot":"","sources":["../src/black76.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAKL,KAAK,UAAU,EAShB,MAAM,0BAAoB,CAAC;AAO5B,OAAO,EAEL,KAAK,MAAM,EAIZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAMzD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AACD,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,IAAI,EAAE,UAAU,CAAC;CAClB;AACD,MAAM,WAAW,6BAA6B;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,UAAU,CAAC;CAClB;AACD,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,iBAAiB,EAAE,YAAY,CAAC,CAAC;AA0D5E;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAU7D;AAED,gGAAgG;AAChG,wBAAgB,aAAa,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAoB9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,iBAAiB,GAAG,cAAc,CAqC9E;AAED,8CAA8C;AAC9C,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf,CAmBA;AAED,MAAM,WAAW,8BAA8B;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EACH,iBAAiB,GACjB,iBAAiB,GACjB,wBAAwB,GACxB,YAAY,GACZ,gBAAgB,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,6BAA6B,GACnC,8BAA8B,CA6DhC;AAyOD,qCAAqC;AACrC,eAAO,MAAM,OAAO,EAAE;IACpB,IAAI,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACnC,GAAG,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;IACzC,MAAM,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;IAC1C,cAAc,EAAE,MAAM,CAAC,iBAAiB,EAAE,cAAc,CAAC,CAAC;IAC1D,iBAAiB,EAAE,MAAM,CACvB,6BAA6B,EAC7B,MAAM,EACN,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EACpB,MAAM,GAAG,IAAI,CACd,CAAC;CAaC,CAAC"}