@aegis-engine/core 0.4.0 → 0.6.0

package/dist/engine/lendHistory.d.ts

@@ -0,0 +1,21 @@
+import type { AegisEngineMetricHistory } from './types.js';
+export type AegisEngineLendShareGrowthSummary = Readonly<{
+    startTimestamp: number;
+    endTimestamp: number;
+    coverageSeconds: number;
+    apyPct: number;
+    weeklyEarningsPer100Usd: number;
+    /** Historical average weekly dollars per $100, recalculated from the first
+     * usable share-price observation through each later observation. */
+    points: ReadonlyArray<Readonly<{
+        t: number;
+        v: number;
+    }>>;
+}>;
+/**
+ * Converts the Engine history plane's realized share-price growth into a
+ * player-readable historical earnings rate. This deliberately does not use
+ * `lendApyPct`: that field is the current borrower-interest model, while share
+ * growth records what actually accrued to one pool share during the window.
+ */
+export declare function summarizeEngineLendShareGrowth(history: AegisEngineMetricHistory): AegisEngineLendShareGrowthSummary | null;

package/dist/engine/positionStrategy.d.ts

@@ -0,0 +1,15 @@
+import type { AegisEnginePosition, AegisEnginePositionVaultActivity, AegisEngineTradePositionIntent, AegisEngineTradePositionStrategy } from './types.js';
+/** Runtime boundary for host-provided or browser-persisted strategy intent. */
+export declare function isAegisEngineTradePositionIntent(value: unknown): value is AegisEngineTradePositionIntent;
+/**
+ * Recognize the current Tap Long/Short opening recipe from indexed Engine
+ * actions. The discriminator is deliberately strict:
+ *
+ * create → one-sided deposit → positive debt → internal swap withdrawal →
+ * opposite-side swap deposit → lock, with no later idle withdrawal.
+ *
+ * A normal Borrow swap has a final user-side withdrawal after its swap output,
+ * so it does not satisfy this shape. Direction comes from the swap input side:
+ * selling token1 for token0 is Long token0; selling token0 is Short token0.
+ */
+export declare function deriveEngineTradePositionStrategy(position: AegisEnginePosition, vault: AegisEnginePositionVaultActivity, intents?: readonly AegisEngineTradePositionIntent[]): AegisEngineTradePositionStrategy | null;

package/dist/engine/quotes.d.ts

@@ -1,4 +1,4 @@
-import type { AegisEngineBorrowCapacity, AegisEngineBorrowCapacityInput, AegisEngineBorrowQuote, AegisEngineBorrowQuoteInput, AegisEngineAddCollateralQuoteInput, AegisEngineCloseQuoteInput, AegisEngineDepositQuote, AegisEngineDepositQuoteInput, AegisEngineIdleWithdrawQuoteInput, AegisEnginePositionActionQuote, AegisEngineRedeemQuoteInput, AegisEngineRepayQuoteInput } from './types.js';
+import type { AegisEngineBorrowCapacity, AegisEngineBorrowCapacityInput, AegisEngineBorrowQuote, AegisEngineBorrowQuoteInput, AegisEngineAddCollateralQuoteInput, AegisEngineCloseQuoteInput, AegisEngineDepositQuote, AegisEngineDepositQuoteInput, AegisEngineIdleWithdrawQuoteInput, AegisEnginePositionActionQuote, AegisEngineRedeemQuoteInput, AegisEngineRepayQuoteInput, AegisEngineTradeOpenQuote, AegisEngineTradeOpenQuoteInput } from './types.js';
 export declare function quoteEngineDeposit(input: AegisEngineDepositQuoteInput): Promise<AegisEngineDepositQuote>;
 export declare function quoteEngineBorrow(input: AegisEngineBorrowQuoteInput): Promise<AegisEngineBorrowQuote>;
 export declare function quoteEngineAddCollateral(input: AegisEngineAddCollateralQuoteInput): Promise<AegisEnginePositionActionQuote>;
@@ -7,3 +7,12 @@ export declare function quoteEngineRepay(input: AegisEngineRepayQuoteInput): Pro
 export declare function quoteEngineCloseVault(input: AegisEngineCloseQuoteInput): Promise<AegisEnginePositionActionQuote>;
 export declare function quoteEngineIdleWithdraw(input: AegisEngineIdleWithdrawQuoteInput): Promise<AegisEnginePositionActionQuote>;
 export declare function quoteEngineRedeem(input: AegisEngineRedeemQuoteInput): Promise<AegisEnginePositionActionQuote>;
+/**
+ * Quotes one tap open on a fresh vault: size the α band against a block-pinned
+ * frame, turn the solver's signed `q` into the router's single internal swap,
+ * and encode create → deposit → borrow → swap → deposit → lock as one call.
+ *
+ * Every economic rejection is a typed `infeasibleReason` carrying the bound
+ * that caused it. Only untrusted deployment metadata and malformed input throw.
+ */
+export declare function quoteEngineTradeOpen(input: AegisEngineTradeOpenQuoteInput): Promise<AegisEngineTradeOpenQuote>;

package/dist/engine/reads.d.ts

@@ -1,11 +1,20 @@
 import type { Address } from 'viem';
-import type { AegisEngineBorrowQuoteContext, AegisEngineMarket, AegisEngineMarketReadInput, AegisEngineMarketSnapshot, AegisEnginePositionsHydration, AegisEnginePositionsHydrationInput, AegisEngineVaultActivityEntry } from './types.js';
-export declare class AegisEngineMarketNotReadyError extends Error {
+import { UserFacingError } from '../errors.js';
+import type { AegisEngineBorrowQuoteContext, AegisEngineMarket, AegisEngineMarketMark, AegisEngineMarketReadInput, AegisEngineMarketSnapshot, AegisEnginePositionsHydration, AegisEnginePositionsHydrationInput, AegisEngineVaultActivityEntry } from './types.js';
+export declare class AegisEngineMarketNotReadyError extends UserFacingError {
     constructor(message: string);
 }
 /** Test-only reset for the module-owned, weakly client-scoped read caches. */
 export declare function clearEngineReadCaches(): void;
 export declare function readEngineMarketSnapshot(input: AegisEngineMarketReadInput): Promise<AegisEngineMarketSnapshot>;
+/**
+ * Live pool mid for one market, in token1-per-token0 display units — the same
+ * price plane `quoteEngineTradeOpen` sizes against. Reuses the market-snapshot
+ * read and its short TTL, so a UI can poll this for each visible market
+ * without new RPC surface: within the freshness window repeated calls join the
+ * in-flight snapshot instead of fanning out.
+ */
+export declare function readEngineMarketMark(input: AegisEngineMarketReadInput): Promise<AegisEngineMarketMark>;
 export declare function readEngineBorrowQuoteContext(input: AegisEngineMarketReadInput, execution?: {
     owner: Address;
     vaultId?: bigint;

package/dist/engine/simpleYield.d.ts

@@ -0,0 +1,39 @@
+import type { AegisEngineLendPositionHydration, AegisEngineLendSharesPosition, AegisEngineMarket, AegisEngineMetricHistory } from './types.js';
+export type AegisEngineSimpleYieldPositionSummaryInput = Readonly<{
+    position: AegisEngineLendSharesPosition | null;
+    market: AegisEngineMarket;
+    hydration?: AegisEngineLendPositionHydration;
+    history?: AegisEngineMetricHistory | null;
+    additionalValueUsd?: number | null;
+    /** Override the current time for deterministic freshness checks. */
+    nowMs?: number;
+}>;
+export type AegisEngineSimpleYieldPositionSummary = Readonly<{
+    hasPosition: boolean;
+    valuation: Readonly<{
+        shareFraction: number;
+        suppliedUsd: number;
+        currentValueUsd: number;
+        source: 'live-shares' | 'indexed-shares';
+    }> | null;
+    projection: Readonly<{
+        addedValueUsd: number;
+        projectedValueUsd: number;
+    }> | null;
+    growth: Readonly<{
+        weeklyEarningsPer100Usd: number;
+        currentWeeklyEarningsUsd: number | null;
+        projectedWeeklyEarningsUsd: number | null;
+        coverageSeconds: number;
+        stale: boolean;
+    }> | null;
+}>;
+/**
+ * Summarizes an Engine lend-share position for a simple-yield surface.
+ *
+ * Live share hydration wins over indexed share balances. Realized weekly
+ * growth comes only from share-price history, never from the market's modeled
+ * `lendApyPct`. Existing positions fail closed when their value is unavailable,
+ * so an add-funds preview cannot accidentally present them as a fresh deposit.
+ */
+export declare function summarizeEngineSimpleYieldPosition(input: AegisEngineSimpleYieldPositionSummaryInput): AegisEngineSimpleYieldPositionSummary;

package/dist/engine/trade/buildTapOpenPosition.d.ts

@@ -0,0 +1,17 @@
+import { type MethodParameters, type TapOpenPositionOptions } from '@labs-solo/aegis-engine-sdk';
+/**
+ * Encode a tap-open without routing internally borrowed swap balances through
+ * the user's wallet.
+ *
+ * SDK 0.30's public builder closes both the Engine and PoolManager deltas via
+ * the message sender. That lands only when both pool tokens have durable
+ * Permit2 caps, even though the user supplies one deposit token. This adapter
+ * keeps the borrowed input and swap output in router custody: TAKE_AE ->
+ * router-funded V4 SETTLE -> router TAKE -> router-funded SETTLE_AE. The only
+ * user-funded transfer is the declared deposit.
+ *
+ * Keep this implementation at the private-SDK boundary. Remove it after the
+ * equivalent builder ships in a newer SDK release and the fork matrix proves
+ * byte-for-byte behavior at that dependency version.
+ */
+export declare function buildWalletMinimalTapOpenPosition(options: TapOpenPositionOptions): MethodParameters;

package/dist/engine/trade/route.d.ts

@@ -0,0 +1,24 @@
+import type { V4Route } from '@labs-solo/aegis-engine-sdk';
+import type { Address, PublicClient } from 'viem';
+import type { AegisEngineBorrowQuoteContext, AegisEngineToken } from '../types.js';
+import type { AegisEngineTapSwapLeg } from './swapLeg.js';
+export type AegisEngineTapRoute = {
+    /** One path, one hop — the pool the vault already borrows against. */
+    route: V4Route;
+    amountOutQuoted: bigint;
+    /** What `addSwapActionsToPlanner` will encode as `amountOutMinimum`. */
+    amountOutMinimum: bigint;
+    /** Block the quote was simulated at. */
+    blockNumber: bigint;
+};
+export type AegisEngineTapRouteInput = {
+    publicClient: PublicClient;
+    /** Registry-trusted Uniswap V4 Quoter. */
+    quoter: Address;
+    context: AegisEngineBorrowQuoteContext;
+    token0: AegisEngineToken;
+    token1: AegisEngineToken;
+    leg: AegisEngineTapSwapLeg;
+    slippageBps: number;
+    signal?: AbortSignal;
+};

package/dist/engine/trade/sizing.d.ts

@@ -0,0 +1,136 @@
+import type { AegisEngineTradeDirection } from '../types.js';
+import { type AegisEngineTapRateBasis, type AegisEngineTapState } from './systemState.js';
+import { type SolverMajors } from './units.js';
+/**
+ * Legacy root preference retained for source compatibility. Spec-0168 makes
+ * selection deterministic: both values now resolve through the debt-minimizing
+ * frontier and ties always choose the lower-γ candidate.
+ *
+ * @deprecated The value is ignored.
+ */
+export type AegisEngineTapRootPolicy = 'min-carry' | 'max-leverage';
+/** Which side of the pair the collateral is denominated in. */
+export type AegisEngineTapDepositAsset = 'token0' | 'token1';
+export type AegisEngineTapSizingInput = {
+    state: AegisEngineTapState;
+    direction: AegisEngineTradeDirection;
+    depositAsset: AegisEngineTapDepositAsset;
+    /** Deposit in solver majors. */
+    depositAmount: SolverMajors;
+    /** Horizon the target LTV is derived from, in seconds. */
+    tlSeconds: number;
+    /** Relative price move to the target: P_T = P_pool · (1 + Δ_lev). Its sign is
+     *  forced to match `direction`; zero has no target and is rejected. */
+    deltaLev: number;
+    /** Absolute ceiling on the opening LTV, independent of the horizon. */
+    tauBar: number;
+    /** When present, invert the band to this average leverage instead of taking
+     *  the leverage-maximising candidate. */
+    leverageTarget?: number;
+    /** @deprecated Ignored; selection always uses the debt-minimizing frontier. */
+    rootPolicy?: AegisEngineTapRootPolicy;
+};
+export type AegisEngineTapCandidate = {
+    /** Exposure ratio the sweep evaluated. */
+    alpha: number;
+    /** Average leverage over the move to the target price; always positive. */
+    leverage: number;
+    /** Instantaneous leverage at entry. */
+    localLeverage: number;
+    /** Leverage as price runs away from entry. */
+    asymptoticLeverage: number;
+    /** Opening LTV. Identical across the band — δ is sized to hit τ. */
+    ltv: number;
+    /** Borrow principal δ (L majors). */
+    delta: SolverMajors;
+    /** Real debt γ = δ·M (L majors). The only quantity that separates the two
+     *  roots at one leverage. */
+    gamma: SolverMajors;
+    /** Post-swap token0 balance (token0 majors). */
+    x: SolverMajors;
+    /** Post-swap token1 balance (token1 majors). */
+    y: SolverMajors;
+    /** Signed internal swap: x = x_b + q, y = y_b − P·q. Positive buys token0. */
+    q: SolverMajors;
+    /** Entry equity (token1 majors). Constant across the band and equal to the
+     *  deposit — borrowing is value-neutral at the pool price. */
+    equity: SolverMajors;
+    /** Equity at the target price (token1 majors). */
+    equityAtTarget: SolverMajors;
+    /** Simple interest over `tlSeconds` at the sized rate (token1 majors). */
+    interestCost: SolverMajors;
+    /** Minimum of E(P) over ALL prices: E_min = ȳ − γ²/x̄ (token1 majors).
+     *  An equity floor, NOT a liquidation level — equity never reaches zero. */
+    equityMin: SolverMajors;
+    /** E_min / E_0. */
+    equityMinRatio: number;
+    cappedByDelta: boolean;
+};
+export type AegisEngineTapSizingDiagnostics = {
+    /** Opening LTV the band was sized to. */
+    tau: number;
+    /** Which of the three inputs set τ. */
+    tauBinding: 'theta-margin' | 'tau-bar' | 'horizon';
+    /** Market OPEN cap θ_L. */
+    thetaL: number;
+    /** Liquidation threshold. The countdown's target — see
+     *  {@link tapDaysToLiquidation}. */
+    thetaLiq: number;
+    /** Annual rate τ and the carry were priced at. */
+    rEffAnnual: number;
+    /** Where that rate came from. */
+    rateBasis: AegisEngineTapRateBasis;
+    entryPrice: number;
+    targetPrice: number;
+    /** δ ceiling from the utilisation cap (L majors). */
+    deltaCap: SolverMajors;
+    /** Deposit above which the cap starts binding; null when uncapped. */
+    maxEfficientDeposit: SolverMajors | null;
+    /** True when the cap moved the winner off the unconstrained optimum. */
+    isCapConstrained: boolean;
+    candidatesTotal: number;
+    candidatesSurviving: number;
+};
+export type AegisEngineTapInfeasibleReason = 
+/** Deposit, horizon, τ̄, or leverage target outside its domain. */
+{
+    kind: 'invalid-input';
+}
+/** Δ_lev = 0. The solver rejects a target equal to entry. */
+ | {
+    kind: 'zero-price-move';
+}
+/** Δ_lev non-finite, or ≤ −100% on a short. */
+ | {
+    kind: 'price-move-out-of-range';
+} | {
+    kind: 'invalid-market-state';
+} | {
+    kind: 'no-borrow-capacity';
+} | {
+    kind: 'deposit-above-max';
+    maxEfficientDeposit: SolverMajors;
+} | {
+    kind: 'no-feasible-band';
+}
+/** @deprecated Valid leverage requests are clamped to `lMax`. */
+ | {
+    kind: 'leverage-above-max';
+    lMax: number;
+}
+/** @deprecated Valid leverage requests are clamped to `lMin`. */
+ | {
+    kind: 'leverage-below-min';
+    lMin: number;
+};
+export type AegisEngineTapSizingResult = {
+    /** Lowest average leverage on the openable debt-minimizing frontier. */
+    lMin: number | null;
+    /** Highest average leverage on that frontier in the requested direction. */
+    lMax: number | null;
+    chosen: AegisEngineTapCandidate | null;
+    candidates: readonly AegisEngineTapCandidate[];
+    /** Null only when the inputs never reached the solver. */
+    diagnostics: AegisEngineTapSizingDiagnostics | null;
+    infeasibleReason?: AegisEngineTapInfeasibleReason;
+};

package/dist/engine/trade/swapLeg.d.ts

@@ -0,0 +1,32 @@
+import type { AegisEngineTradeDirection } from '../types.js';
+import type { AegisEngineTapCandidate } from './sizing.js';
+import { type SolverMajors } from './units.js';
+/** Floor-converts an amount in solver majors to token base units. */
+export declare function tokenBaseUnits(value: SolverMajors, decimals: number): bigint;
+export type AegisEngineTapSwapLeg = {
+    /** False when `q` is dust — the borrow already delivers the target mix. */
+    needed: boolean;
+    inputIsToken0: boolean;
+    /** Floor-rounded, and never above the idle the vault holds after the borrow. */
+    amountIn: bigint;
+    /** True when vault idle, not the solver, set `amountIn`. */
+    clampedByIdle: boolean;
+};
+export type AegisEngineTapSwapLegResult = {
+    ok: true;
+    leg: AegisEngineTapSwapLeg;
+} | {
+    ok: false;
+    reason: 'swap-direction-mismatch' | 'insufficient-idle';
+};
+export type AegisEngineTapSwapLegInput = {
+    candidate: AegisEngineTapCandidate;
+    direction: AegisEngineTradeDirection;
+    /** Pool mid price, token1 per token0. The solver settles `q` at this price. */
+    entryPrice: number;
+    decimals0: number;
+    decimals1: number;
+    /** Vault idle after the collateral deposit and the borrow, in base units. */
+    idle0: bigint;
+    idle1: bigint;
+};

package/dist/engine/trade/systemState.d.ts

@@ -0,0 +1,44 @@
+import type { Address } from 'viem';
+import type { AegisEngineVersion } from '../types.js';
+/** Which rate the horizon, the carry, and the countdown were priced at. */
+export type AegisEngineTapRateBasis = 'projected-post-borrow' | 'current-apr';
+export type AegisEngineTapRate = {
+    aprPct: number;
+    basis: AegisEngineTapRateBasis;
+};
+/**
+ * The α-sweep's market state plus the two things the sweep does not model: the
+ * liquidator's threshold, and the inputs that reprice the market after our own
+ * borrow.
+ */
+export type AegisEngineTapState = {
+    /** Pool price, token1 per token0. */
+    Ppool: number;
+    /** Idle liquidity S, in solver majors. */
+    SIdle: number;
+    /** Global real debt B_M, in solver majors. */
+    BM: number;
+    /** Borrow index M. */
+    M: number;
+    /** Utilisation cap Ū. */
+    Ucap: number;
+    /** The OPEN cap. Sizing may not cross it. */
+    thetaL: number;
+    /** The liquidator's threshold. The countdown runs to THIS, not to θ_L. */
+    thetaLiq: number;
+    /** Pre-borrow APR. The basis only when the oracle projection is refused. */
+    aprPct: number;
+    /** RESEARCH-0024 deletes β. Never expose it as a setting. */
+    betaTime: number;
+    /** What `estimatePostBorrowRate` needs to reprice this market. */
+    projection: {
+        equityLWad: bigint;
+        borrowedLWad: bigint;
+        fullUtilRate: bigint;
+        rateOracleAddress: Address;
+        chainId: number;
+        version: AegisEngineVersion;
+        /** κ, to carry γ from solver majors back into engine L-WAD. */
+        kappa: number;
+    };
+};

package/dist/engine/trade/units.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Tap sizing crosses three unit systems that are indistinguishable at the type
+ * level until one of them is off by κ or by WAD:
+ *
+ * - {@link EngineL} — WAD-scaled L-units exactly as the engine reports them
+ *   (`equityLWad`, `borrowedLWad`).
+ * - {@link SolverMajors} — decimal-adjusted floats; the space the SDK's α-sweep
+ *   works in (`δ`, `γ`, `x`, `y`, equities).
+ * - {@link RlUnits} — debt principal in the units `modifyDebt` accepts.
+ *
+ * κ = 10^((decimals0 + decimals1) / 2) is the only bridge between engine L and
+ * solver majors. It CANCELS in LTV — numerator γ·κ over denominator √(x̄·ȳ)·κ —
+ * which is exactly why a κ mistake stays invisible in the number a user reads.
+ * It does NOT cancel in the δ-cap comparison or in the principal handed to the
+ * engine: passing raw engine L to `deltaMaxByUtil` overstates borrow capacity by
+ * κ (10^18 on an 18/18 pair) and silently disables the utilisation cap.
+ */
+declare const unitBrand: unique symbol;
+type Unit<T, Name extends string> = T & {
+    readonly [unitBrand]: Name;
+};
+/** WAD-scaled L-units, as read from the engine. */
+export type EngineL = Unit<bigint, 'engine-l-wad'>;
+/** Decimal-adjusted floats — token and L amounts in the solver's own space. */
+export type SolverMajors = Unit<number, 'solver-majors'>;
+/** Debt principal in rL units — what `modifyDebt` takes. */
+export type RlUnits = Unit<bigint, 'rl'>;
+export declare function engineL(value: bigint): EngineL;
+export declare function solverMajors(value: number): SolverMajors;
+/** κ = 10^((d0+d1)/2). Non-integral for an odd decimal sum, hence a float. */
+export declare function kappaForDecimals(decimals0: number, decimals1: number): number;
+export declare function solverMajorsFromEngineL(value: EngineL, kappa: number): SolverMajors;
+/**
+ * Rounds down: the engine is never asked for more principal than was sized.
+ * Past 2⁵³ — where every principal on an 18/18 pair lives — the product is
+ * already an integral float and `Math.floor` is a no-op, so the last digits are
+ * float noise that can sit ABOVE the sized δ. The shift drops one relative ulp,
+ * which is zero below 2⁵² and puts the result under the true product above it.
+ */
+export declare function rlFromSolverMajors(value: SolverMajors, kappa: number): RlUnits;
+export {};