@insiderfinance/totalfinance 0.1.0

package/modules/portfolio/dist/reducer-kernel.js

@@ -0,0 +1,320 @@
+/**
+ * The reducer kernel (FC7 slice 5, 2026-08-29): the ONE set of lot, cash, and position primitives
+ * every economic family folds through. Extracted from `state.ts` so the lifecycle modules
+ * (`lifecycle-derivatives.ts`, `lifecycle-corporate.ts`) and the fill reducer share exactly one
+ * relief law, one lot-opening law, and one cash-booking law — a derivative exercise relieves
+ * option lots and opens underlying lots with the same arithmetic a fill uses.
+ *
+ * Package-internal: `reducer-kernel.ts` is not an entrypoint and nothing here is curated public
+ * surface. Every function operates on the fold's WORKING copy (never on caller data).
+ */
+import { DataError, ErrorCode, InputError } from '../../core/dist/index.js';
+import { canonicalJsonOf } from '../../core/dist/artifacts/index.js';
+import { QUANTITY_DUST, ownValue, setOwnValue } from './internal.js';
+// ---------------------------------------------------------------------------------------------------
+// Accounts and cash
+// ---------------------------------------------------------------------------------------------------
+export function freshAccount() {
+    return {
+        cashBalances: {},
+        positions: {},
+        realizedPnl: {},
+        incomeReceived: {},
+        transactionCosts: {},
+        financingCosts: {},
+        realizedPnlByInstrument: {},
+        incomeByInstrument: {},
+        transactionCostsByInstrument: {},
+    };
+}
+export function accountOf(state, accountId) {
+    const existing = ownValue(state.accounts, accountId);
+    if (existing !== undefined)
+        return existing;
+    const created = freshAccount();
+    setOwnValue(state.accounts, accountId, created);
+    return created;
+}
+export function cashOf(account, currency) {
+    const existing = ownValue(account.cashBalances, currency);
+    if (existing !== undefined)
+        return existing;
+    const created = { totalAmount: 0, settlementSchedule: [] };
+    setOwnValue(account.cashBalances, currency, created);
+    return created;
+}
+export function addTo(record, currency, delta) {
+    setOwnValue(record, currency, (ownValue(record, currency) ?? 0) + delta);
+}
+export function addToInstrument(record, instrumentId, currency, delta) {
+    let byCurrency = ownValue(record, instrumentId);
+    if (byCurrency === undefined) {
+        byCurrency = {};
+        setOwnValue(record, instrumentId, byCurrency);
+    }
+    addTo(byCurrency, currency, delta);
+}
+/** Book a signed cash amount; a dated leg joins the settlement schedule. */
+export function bookCash(account, currency, amount, eventId, settleTimestampMs) {
+    const cash = cashOf(account, currency);
+    cash.totalAmount += amount;
+    if (settleTimestampMs !== undefined) {
+        cash.settlementSchedule.push({ eventId, amount, settleTimestampMs });
+    }
+}
+export function removeSettlementLeg(account, currency, eventId, amount, settleTimestampMs) {
+    if (settleTimestampMs === undefined || amount === 0)
+        return true;
+    const cash = cashOf(account, currency);
+    const index = cash.settlementSchedule.findIndex((leg) => leg.eventId === eventId &&
+        leg.amount === amount &&
+        leg.settleTimestampMs === settleTimestampMs);
+    if (index < 0)
+        return false;
+    cash.settlementSchedule.splice(index, 1);
+    return true;
+}
+/** Realized P&L (position currency) to the account and the instrument attribution. */
+export function recordRealized(account, instrumentId, currency, realized) {
+    if (realized === 0)
+        return;
+    addTo(account.realizedPnl, currency, realized);
+    addToInstrument(account.realizedPnlByInstrument, instrumentId, currency, realized);
+}
+/** Income (positive) or an income adjustment (negative, e.g. accrued interest paid) attributed. */
+export function recordIncome(account, instrumentId, currency, amount) {
+    if (amount === 0)
+        return;
+    addTo(account.incomeReceived, currency, amount);
+    if (instrumentId !== undefined) {
+        addToInstrument(account.incomeByInstrument, instrumentId, currency, amount);
+    }
+}
+// ---------------------------------------------------------------------------------------------------
+// Refusals
+// ---------------------------------------------------------------------------------------------------
+/** A reversal that has no exact inverse — the typed refusal every family shares. */
+export function infeasible(functionName, envelope, detail) {
+    throw new DataError(`${functionName}: ${envelope.event.eventType} '${envelope.eventId}' cannot reverse '${envelope.reversesEventId}' exactly — ${detail} History is never approximated; record the correcting economic event instead.`, {
+        code: ErrorCode.PortfolioReversalInfeasible,
+        context: {
+            function: functionName,
+            eventId: envelope.eventId,
+            reversesEventId: envelope.reversesEventId,
+        },
+    });
+}
+/** A lifecycle event that names a position the account does not hold. */
+export function requireHeldPosition(functionName, account, envelope, instrumentId, field) {
+    const position = ownValue(account.positions, instrumentId);
+    if (position === undefined) {
+        throw new InputError(`${functionName}: ${envelope.event.eventType} event '${envelope.eventId}' names ${instrumentId}, but account '${envelope.accountId}' holds no open position in it — a lifecycle event transforms held lots, so record the position's fills first or drop the event for this account.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field, eventId: envelope.eventId },
+        });
+    }
+    return position;
+}
+/**
+ * The account's open position for `instrumentId`, created from `profile` when absent. An existing
+ * position must AGREE with the profile (one currency, one multiplier, one settlement style, one
+ * set of contract terms per open position) — a disagreement is a typed refusal, never a silent
+ * re-profile.
+ */
+export function ensurePosition(functionName, account, envelope, instrumentId, profile, field) {
+    const existing = ownValue(account.positions, instrumentId);
+    if (existing === undefined) {
+        const created = {
+            instrumentId,
+            currency: profile.currency,
+            contractMultiplier: profile.contractMultiplier,
+            settlementStyle: profile.settlementStyle,
+            quantity: 0,
+            lots: [],
+        };
+        if (profile.contract !== undefined)
+            created.contract = profile.contract;
+        setOwnValue(account.positions, instrumentId, created);
+        return created;
+    }
+    const disagreement = existing.currency !== profile.currency
+        ? `currency ${profile.currency} vs the open position's ${existing.currency}`
+        : existing.contractMultiplier !== profile.contractMultiplier
+            ? `contractMultiplier ${profile.contractMultiplier} vs the open position's ${existing.contractMultiplier}`
+            : existing.settlementStyle !== profile.settlementStyle
+                ? `settlementStyle '${profile.settlementStyle}' vs the open position's '${existing.settlementStyle}'`
+                : canonicalJsonOf(existing.contract ?? null) !== canonicalJsonOf(profile.contract ?? null)
+                    ? `contract terms that differ from the open position's`
+                    : null;
+    if (disagreement !== null) {
+        throw new InputError(`${functionName}: ${envelope.event.eventType} event '${envelope.eventId}' describes ${instrumentId} with ${disagreement} in account '${envelope.accountId}' — one profile per open position. Close the position first, or record the event with the position's own profile.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field, eventId: envelope.eventId },
+        });
+    }
+    return existing;
+}
+/** Open one lot with the fold's deterministic id and return it. */
+export function openLot(state, position, signedQuantity, costBasisPerUnit, envelope) {
+    state.lotSequence += 1;
+    const lot = {
+        lotId: `lot-${state.lotSequence}`,
+        openedByEventId: envelope.eventId,
+        openedTimestampMs: envelope.effectiveTimestampMs,
+        quantity: signedQuantity,
+        costBasisPerUnit,
+    };
+    position.lots.push(lot);
+    return lot;
+}
+/**
+ * Policy-ordered view of a position's lots for relief (never reorders the stored array). Also
+ * consumed by `proposePortfolioRebalance` to preview EXACTLY the lots a fill would relieve — one
+ * ordering law, proven by the parity test in `test/rebalance.test.ts`.
+ */
+export function reliefOrder(lots, policy) {
+    if (policy === 'fifo')
+        return [...lots];
+    if (policy === 'lifo')
+        return [...lots].reverse();
+    // 'highest-cost': descending per-unit basis, stable (ties keep chronological order). For short
+    // lots `costBasisPerUnit` records opening proceeds per unit; the same descending order applies —
+    // documented in docs/specs/fc7-first-slice.md.
+    return [...lots].sort((a, b) => b.costBasisPerUnit - a.costBasisPerUnit);
+}
+function relieveFromLot(position, lot, quantityRelieved, pricePerUnit) {
+    const isLong = lot.quantity > 0;
+    const realizedPerUnit = isLong
+        ? (pricePerUnit - lot.costBasisPerUnit) * quantityRelieved
+        : (lot.costBasisPerUnit - pricePerUnit) * quantityRelieved;
+    lot.quantity += isLong ? -quantityRelieved : quantityRelieved;
+    if (Math.abs(lot.quantity) <= QUANTITY_DUST) {
+        const index = position.lots.indexOf(lot);
+        position.lots.splice(index, 1);
+    }
+    return realizedPerUnit * position.contractMultiplier;
+}
+/**
+ * Relieve `quantity` (unsigned) of a position's open lots at `pricePerUnit` under the state's
+ * relief policy — or under explicit `lotSelections` when the policy is `specific-lot`. Realized
+ * P&L carries the contract multiplier. The caller has established that the relief closes against
+ * the position's direction and that `quantity` does not exceed what is held.
+ */
+export function relieveQuantity(functionName, state, envelope, position, quantity, pricePerUnit, lotSelections, field) {
+    const subject = `${envelope.event.eventType} event '${envelope.eventId}'`;
+    const relieved = [];
+    let realized = 0;
+    if (lotSelections !== undefined && state.lotRelief !== 'specific-lot') {
+        throw new InputError(`${functionName}: ${subject} carries ${field}, but this ledger's lotRelief is '${state.lotRelief}' — the selections would be silently ignored. Remove them, or fold under lotRelief: 'specific-lot'.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field, eventId: envelope.eventId },
+        });
+    }
+    if (quantity <= QUANTITY_DUST)
+        return { realizedPnl: 0, relievedQuantity: 0, relieved };
+    if (state.lotRelief === 'specific-lot') {
+        if (lotSelections === undefined) {
+            throw new InputError(`${functionName}: ${subject} closes ${quantity} of ${position.instrumentId} under lotRelief 'specific-lot', so ${field} must name the lots relieved (their quantities summing to ${quantity}).`, {
+                code: ErrorCode.InputMissingField,
+                context: { function: functionName, field, eventId: envelope.eventId },
+            });
+        }
+        const selectedTotal = lotSelections.reduce((sum, s) => sum + s.quantity, 0);
+        if (Math.abs(selectedTotal - quantity) > QUANTITY_DUST) {
+            throw new InputError(`${functionName}: ${subject} relieves ${quantity} of ${position.instrumentId}, but its ${field} sum to ${selectedTotal} — specific-lot relief must name exactly the relieved quantity.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { function: functionName, field, eventId: envelope.eventId },
+            });
+        }
+        for (const selection of lotSelections) {
+            const lot = position.lots.find((candidate) => candidate.lotId === selection.lotId);
+            if (lot === undefined) {
+                throw new DataError(`${functionName}: ${subject} names lot '${selection.lotId}', which does not exist in the ${position.instrumentId} position of account '${envelope.accountId}' — lot relief never guesses a substitute. Open lots: ${position.lots.map((l) => `${l.lotId} (${l.quantity})`).join(', ') || 'none'}.`, {
+                    code: ErrorCode.PortfolioLotUnavailable,
+                    context: { function: functionName, lotId: selection.lotId, eventId: envelope.eventId },
+                });
+            }
+            if (Math.abs(lot.quantity) + QUANTITY_DUST < selection.quantity) {
+                throw new DataError(`${functionName}: ${subject} relieves ${selection.quantity} from lot '${selection.lotId}', which holds only ${Math.abs(lot.quantity)}.`, {
+                    code: ErrorCode.PortfolioLotUnavailable,
+                    context: { function: functionName, lotId: selection.lotId, eventId: envelope.eventId },
+                });
+            }
+            const basis = lot.costBasisPerUnit;
+            const lotRealized = relieveFromLot(position, lot, selection.quantity, pricePerUnit);
+            realized += lotRealized;
+            relieved.push({
+                lotId: selection.lotId,
+                quantity: selection.quantity,
+                costBasisPerUnit: basis,
+                realizedPnl: lotRealized,
+            });
+        }
+    }
+    else {
+        let remaining = quantity;
+        for (const lot of reliefOrder(position.lots, state.lotRelief)) {
+            if (remaining <= QUANTITY_DUST)
+                break;
+            const take = Math.min(Math.abs(lot.quantity), remaining);
+            const basis = lot.costBasisPerUnit;
+            const lotId = lot.lotId;
+            const lotRealized = relieveFromLot(position, lot, take, pricePerUnit);
+            realized += lotRealized;
+            relieved.push({ lotId, quantity: take, costBasisPerUnit: basis, realizedPnl: lotRealized });
+            remaining -= take;
+        }
+    }
+    return { realizedPnl: realized, relievedQuantity: quantity, relieved };
+}
+/** Recompute the signed quantity from the lots and drop an empty position. */
+export function finalizePosition(account, position) {
+    position.quantity = position.lots.reduce((sum, lot) => sum + lot.quantity, 0);
+    if (Math.abs(position.quantity) <= QUANTITY_DUST && position.lots.length === 0) {
+        delete account.positions[position.instrumentId];
+    }
+}
+/** The held (unsigned) quantity a closing event may relieve, with the direction it closes. */
+export function closingCapacity(functionName, envelope, position, quantity, field) {
+    if (Math.abs(position.quantity) + QUANTITY_DUST < quantity) {
+        throw new InputError(`${functionName}: ${envelope.event.eventType} event '${envelope.eventId}' settles ${quantity} of ${position.instrumentId}, but account '${envelope.accountId}' holds ${Math.abs(position.quantity)} — a lifecycle event never settles more than is held; record the quantity actually settled.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field, eventId: envelope.eventId },
+        });
+    }
+}
+/**
+ * Fold one side of a trade into a position — THE lot law a fill, an exercise, an assignment, and
+ * a roll share: a buy covers short lots before opening a long lot; a sell relieves long lots
+ * before opening a short lot. Cash is the caller's (the delivery price and the lot price differ
+ * under `'fold-into-underlying-basis'`). `lotSelections` name the relieved lots under
+ * `specific-lot`; a DERIVED leg (`derivedLegName` given — the delivered underlying, a roll's
+ * successor) whose lots the event cannot name is a typed refusal under that policy, never a
+ * silent pick; a direct leg (a fill) falls through to `relieveQuantity`'s own teaching.
+ */
+export function foldPositionLeg(functionName, state, account, envelope, position, side, quantity, pricePerUnit, lotSelections, field, derivedLegName) {
+    const opposing = (side === 'buy' && position.quantity < 0) || (side === 'sell' && position.quantity > 0);
+    const closingQuantity = opposing ? Math.min(quantity, Math.abs(position.quantity)) : 0;
+    let realized = 0;
+    if (closingQuantity > QUANTITY_DUST) {
+        if (derivedLegName !== undefined &&
+            state.lotRelief === 'specific-lot' &&
+            lotSelections === undefined) {
+            throw new InputError(`${functionName}: ${envelope.event.eventType} event '${envelope.eventId}' ${derivedLegName} ${side === 'buy' ? 'covers' : 'relieves'} ${closingQuantity} of the ${position.quantity > 0 ? 'long' : 'short'} ${position.instrumentId} position held in account '${envelope.accountId}', and this ledger's lotRelief is 'specific-lot' — the event names the contract lots it settles, not the ${position.instrumentId} lots this leg would relieve, and lot relief never guesses a lot. Close the ${position.instrumentId} lots first with a trade.fill carrying lotSelections, or fold under fifo | lifo | highest-cost.`, {
+                code: ErrorCode.InputMissingField,
+                context: { function: functionName, field, eventId: envelope.eventId },
+            });
+        }
+        realized = relieveQuantity(functionName, state, envelope, position, closingQuantity, pricePerUnit, lotSelections, field).realizedPnl;
+    }
+    recordRealized(account, position.instrumentId, position.currency, realized);
+    const openingQuantity = quantity - closingQuantity;
+    const openedLotIds = [];
+    if (openingQuantity > QUANTITY_DUST) {
+        const lot = openLot(state, position, side === 'buy' ? openingQuantity : -openingQuantity, pricePerUnit, envelope);
+        openedLotIds.push(lot.lotId);
+    }
+    finalizePosition(account, position);
+    return { realizedPnl: realized, relievedQuantity: closingQuantity, openedLotIds };
+}
+//# sourceMappingURL=reducer-kernel.js.map

package/modules/portfolio/dist/reducer-kernel.js.map

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

package/modules/portfolio/dist/snapshot.d.ts

@@ -0,0 +1,128 @@
+/**
+ * `portfolioSnapshot` — explicit market/as-of valuation of a derived {@link PortfolioState}
+ * (FC7 required API; agent-native Permanent law 2: valuation combines ledger FACTS with an
+ * explicit market snapshot; P&L is a derived report, never ledger state).
+ *
+ * The market is a Gate B `MarketSnapshot` (`@insiderfinance/totalfinance/core/artifacts`) — the platform's ONE
+ * container for "market state at an instant" — validated through `readMarketSnapshot` so there is
+ * exactly one validator. Position marks come from `observations.spots`; base-currency conversion
+ * uses explicit {@link CurrencyPairQuote}s in FC5's vocabulary and arithmetic (see
+ * `internal.ts`). An unavailable mark or quote is a TYPED failure
+ * (`portfolio.mark_unavailable`) — never an interpolation, a stale guess, or a silent skip.
+ *
+ * The settled/unsettled cash split happens HERE, against the explicit `asOf`: the fold records
+ * each dated cash leg; this call classifies legs settling after `asOf` as receivable (incoming)
+ * or payable (outgoing). That keeps the reducer clock-free while the report states
+ * trade-date-vs-settlement-date truth (FC7 mandatory state).
+ */
+import type { EpochMs } from '../../core/dist/index.js';
+import type { MarketSnapshot } from '../../core/dist/artifacts/index.js';
+import type { CurrencyPairQuote } from './internal.js';
+import type { SettlementStyle } from './events.js';
+import type { LotReliefPolicy, PortfolioState } from './state.js';
+/** Input for {@link portfolioSnapshot}. */
+export interface PortfolioSnapshotInput {
+    /** A derived {@link PortfolioState} (from `applyPortfolioEvents` or `ledger.state`). */
+    portfolio: PortfolioState;
+    /** The valuation instant: epoch ms, `'YYYY-MM-DD'`, or a zoned ISO datetime. */
+    asOf: EpochMs | string;
+    /** The Gate B market snapshot supplying instrument marks. */
+    market: MarketSnapshot;
+    /**
+     * Explicit valuation-time exchange-rate quotes (FC5 vocabulary), one per currency pair, in
+     * either orientation. Required exactly when the portfolio holds cash or positions outside its
+     * base currency.
+     */
+    currencyConversions?: CurrencyPairQuote[];
+}
+/** One account × currency cash row at the valuation instant. */
+export interface PortfolioSnapshotCashRow {
+    accountId: string;
+    currency: string;
+    /** The booked balance including unsettled legs. */
+    totalAmount: number;
+    /** `totalAmount − unsettledReceivable + unsettledPayable` (the tested identity). */
+    settledAmount: number;
+    /** Magnitude of incoming cash legs settling after `asOf` (receivable), ≥ 0. */
+    unsettledReceivable: number;
+    /** Magnitude of outgoing cash legs settling after `asOf` (payable), ≥ 0. */
+    unsettledPayable: number;
+    /** `totalAmount` in the portfolio's base currency at the supplied conversion quote. */
+    baseCurrencyValue: number;
+}
+/** One valued position at the valuation instant. */
+export interface PortfolioSnapshotPosition {
+    accountId: string;
+    instrumentId: string;
+    /** The position's trading currency (marks must be quoted in it). */
+    currency: string;
+    quantity: number;
+    markPricePerUnit: number;
+    /** Units of the underlying per unit of quantity (slice 5): shares 1, an option's 100, a futures size. */
+    contractMultiplier: number;
+    settlementStyle: SettlementStyle;
+    /**
+     * The position's contribution to NAV, in `currency`: `quantity × mark × multiplier` for a
+     * cash-on-trade position; for a variation-margin position the UNSETTLED P&L since the last
+     * settlement, `Σ (mark − lot basis) × lot quantity × multiplier` (its notional is not owned).
+     */
+    marketValue: number;
+    baseCurrencyMarketValue: number;
+    /** `quantity × mark × multiplier` — the economic exposure, in `currency` (equals marketValue for cash-on-trade). */
+    notionalValue: number;
+    baseCurrencyNotionalValue: number;
+    /** Remaining open-lot basis `Σ lot.quantity × lot.costBasisPerUnit × multiplier` (signed), in `currency`; 0 for variation-margin positions (their basis is the last settlement, not capital). */
+    costBasis: number;
+    /** `marketValue − costBasis`, in `currency` — mark-to-market on the OPEN lots only. */
+    unrealizedPnl: number;
+    baseCurrencyUnrealizedPnl: number;
+    lotCount: number;
+}
+/** Result of {@link portfolioSnapshot}. */
+export interface PortfolioSnapshotResult {
+    asOf: EpochMs;
+    baseCurrency: string;
+    /** `totalCashBaseCurrencyValue + totalPositionsBaseCurrencyValue` (the tested identity). */
+    netAssetValue: number;
+    /** Sorted by (accountId, currency) — deterministic. */
+    cash: PortfolioSnapshotCashRow[];
+    totalCashBaseCurrencyValue: number;
+    /** Sorted by (accountId, instrumentId) — deterministic. */
+    positions: PortfolioSnapshotPosition[];
+    totalPositionsBaseCurrencyValue: number;
+    assumptions: {
+        conventionsVersion: string;
+        /** The relief policy behind every realized figure in the underlying state — echoed. */
+        lotRelief: LotReliefPolicy;
+        /** The market snapshot's own instant — a warning discloses any mismatch with `asOf`. */
+        marketAsOf: EpochMs;
+        /** The exchange-rate quotes actually used, echoed verbatim. */
+        currencyConversionsUsed: CurrencyPairQuote[];
+        /** Prose statement of the valuation convention. String-typed by design. */
+        valuationConvention: string;
+    };
+    diagnostics: {
+        warnings: string[];
+        accountCount: number;
+        positionCount: number;
+    };
+}
+/**
+ * Value a portfolio state against an explicit market snapshot at an explicit instant.
+ *
+ * @example
+ * ```ts
+ * import { createMarketSnapshot } from '@insiderfinance/totalfinance/core/artifacts';
+ * import { applyPortfolioEvents, portfolioSnapshot } from '@insiderfinance/totalfinance/portfolio';
+ *
+ * const state = applyPortfolioEvents({ portfolio: { baseCurrency: 'USD' }, events });
+ * const market = createMarketSnapshot({
+ *   asOf: '2026-08-20',
+ *   observations: { spots: { AAPL: { price: 232.5, currency: 'USD' } } },
+ * });
+ * const valued = portfolioSnapshot({ portfolio: state, asOf: '2026-08-20', market });
+ * valued.netAssetValue; // cash + positions, in USD
+ * ```
+ */
+export declare function portfolioSnapshot(input: PortfolioSnapshotInput): PortfolioSnapshotResult;
+//# sourceMappingURL=snapshot.d.ts.map

package/modules/portfolio/dist/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAAoB,CAAC;AAYlD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAA8B,CAAC;AAEnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAQvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGlE,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC,wFAAwF;IACxF,SAAS,EAAE,cAAc,CAAC;IAC1B,gFAAgF;IAChF,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB,6DAA6D;IAC7D,MAAM,EAAE,cAAc,CAAC;IACvB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAC3C;AAED,gEAAgE;AAChE,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,aAAa,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,mBAAmB,EAAE,MAAM,CAAC;IAC5B,4EAA4E;IAC5E,gBAAgB,EAAE,MAAM,CAAC;IACzB,uFAAuF;IACvF,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,oDAAoD;AACpD,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,yGAAyG;IACzG,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,eAAe,CAAC;IACjC;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB,EAAE,MAAM,CAAC;IAChC,oHAAoH;IACpH,aAAa,EAAE,MAAM,CAAC;IACtB,yBAAyB,EAAE,MAAM,CAAC;IAClC,iMAAiM;IACjM,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,aAAa,EAAE,MAAM,CAAC;IACtB,yBAAyB,EAAE,MAAM,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,2CAA2C;AAC3C,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,OAAO,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,4FAA4F;IAC5F,aAAa,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,IAAI,EAAE,wBAAwB,EAAE,CAAC;IACjC,0BAA0B,EAAE,MAAM,CAAC;IACnC,2DAA2D;IAC3D,SAAS,EAAE,yBAAyB,EAAE,CAAC;IACvC,+BAA+B,EAAE,MAAM,CAAC;IACxC,WAAW,EAAE;QACX,kBAAkB,EAAE,MAAM,CAAC;QAC3B,uFAAuF;QACvF,SAAS,EAAE,eAAe,CAAC;QAC3B,wFAAwF;QACxF,UAAU,EAAE,OAAO,CAAC;QACpB,+DAA+D;QAC/D,uBAAuB,EAAE,iBAAiB,EAAE,CAAC;QAC7C,2EAA2E;QAC3E,mBAAmB,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,WAAW,EAAE;QACX,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAkBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,uBAAuB,CA2MxF"}