@aegis-engine/core 0.7.0 → 0.8.1

package/dist/engine/registry.d.ts

@@ -1,4 +1,4 @@
-import type { Address } from 'viem';
+import { type Address } from 'viem';
 import type { AegisEngineVersion } from './types.js';
 /** Engine hard utilization cap as a percentage of supplied liquidity.
  *  Mirrors the SDK's UTILIZATION_CAP_PIPS (950_000/1_000_000), inlined so

package/dist/engine/restSchemas.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+export declare const engineAdaptiveTickThresholdModeSchema: z.ZodLiteral<"post_swap_surge_trigger">;
 export declare const enginePoolIdSchema: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
 export declare const engineMarketsRestResponseSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<"1">;
@@ -9,8 +10,21 @@ export declare const engineMarketsRestResponseSchema: z.ZodObject<{
         updatedAt: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
         blockNumber: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         marketCount: z.ZodNumber;
-    }, z.core.$strip>;
+    }, z.core.$strict>;
 }, z.core.$strip>;
+/** Opt-in market envelope from GET /v1/engine/markets/v2. Market rows are
+ * validated by marketAdapter because static and REST rows share normalization. */
+export declare const engineMarketsV2RestResponseSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"2">;
+    chainId: z.ZodNumber;
+    markets: z.ZodArray<z.ZodUnknown>;
+    freshness: z.ZodObject<{
+        source: z.ZodLiteral<"canopy">;
+        updatedAt: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
+        blockNumber: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        marketCount: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
 export declare const engineMarketIdSchema: z.ZodString;
 export declare const engineMetricHistoryRestResponseSchema: z.ZodObject<{
     marketId: z.ZodString;
@@ -52,6 +66,50 @@ export declare const engineMetricHistoryRestResponseSchema: z.ZodObject<{
     }, z.core.$strict>>;
     updatedAt: z.ZodNullable<z.ZodISODateTime>;
 }, z.core.$strict>;
+export declare const engineMetricHistoryV2RestResponseSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"2">;
+    marketId: z.ZodString;
+    resolution: z.ZodLiteral<"12h">;
+    window: z.ZodEnum<{
+        "7d": "7d";
+        "30d": "30d";
+        "60d": "60d";
+    }>;
+    status: z.ZodEnum<{
+        ready: "ready";
+        warming_up: "warming_up";
+        no_data: "no_data";
+    }>;
+    pointCount: z.ZodNumber;
+    points: z.ZodArray<z.ZodObject<{
+        t: z.ZodNumber;
+        observedAt: z.ZodISODateTime;
+        blockNumber: z.ZodNumber;
+        utilizationPct: z.ZodNullable<z.ZodNumber>;
+        borrowAprPct: z.ZodNullable<z.ZodNumber>;
+        lendApyPct: z.ZodNullable<z.ZodNumber>;
+        ratePerSecondWad: z.ZodNullable<z.ZodString>;
+        rateSource: z.ZodNullable<z.ZodString>;
+        fullUtilizationRate: z.ZodNullable<z.ZodString>;
+        sharePriceWad: z.ZodNullable<z.ZodString>;
+        suppliedUsd: z.ZodNullable<z.ZodNumber>;
+        borrowedUsd: z.ZodNullable<z.ZodNumber>;
+        availableToBorrowUsd: z.ZodNullable<z.ZodNumber>;
+        baseFeePpm: z.ZodNullable<z.ZodNumber>;
+        activeFeePpm: z.ZodNullable<z.ZodNumber>;
+        surgeFeePpm: z.ZodNullable<z.ZodNumber>;
+        feeSource: z.ZodNullable<z.ZodString>;
+        surgeActive: z.ZodNullable<z.ZodBoolean>;
+        inCapEvent: z.ZodNullable<z.ZodBoolean>;
+        manualOverride: z.ZodNullable<z.ZodBoolean>;
+        perSwapMode: z.ZodNullable<z.ZodBoolean>;
+        warnings: z.ZodArray<z.ZodString>;
+        adaptiveTickThresholdTicks: z.ZodNullable<z.ZodNumber>;
+        adaptiveTickThresholdMode: z.ZodNullable<z.ZodLiteral<"post_swap_surge_trigger">>;
+        feeObservedAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strict>>;
+    updatedAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
 export declare const enginePositionsRestResponseSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<"1">;
     chainId: z.ZodNumber;

package/dist/engine/tradeExecutionSession.d.ts

@@ -0,0 +1,155 @@
+import type { Address, Hex, PublicClient } from 'viem';
+import type { AegisSwapChainConfig } from '../config/index.js';
+import { type ClassifiedError } from '../errors.js';
+import { type AegisTransactionObservation } from '../swap/receiptWait.js';
+import { type Eip1193Provider } from '../wallet.js';
+import type { AegisEngineApprovalInput, AegisEngineAuthorizationPlan, AegisEngineAuthorizationStepKind, AegisEngineMarket, AegisEngineToken, AegisEngineTradeDirection, AegisEngineTradeOpenQuote, AegisEngineTransactionResult } from './types.js';
+export type AegisEngineTradeOpenIntent = Readonly<{
+    owner: Address;
+    market: AegisEngineMarket;
+    direction: AegisEngineTradeDirection;
+    token: AegisEngineToken;
+    amount: bigint;
+    leverage?: number;
+    horizonSeconds: number;
+    priceMove: number;
+    slippageBps: number;
+    maxPriceImpactBps: number;
+    approvalMode: 'exact' | 'max';
+}>;
+export type AegisEngineTradeExecutionStepStatus = 'planned' | 'wallet-requested' | 'submitted' | 'confirmed' | 'failed' | 'cancelled';
+export type AegisEngineTradeExecutionStep = Readonly<{
+    kind: AegisEngineAuthorizationStepKind;
+    status: AegisEngineTradeExecutionStepStatus;
+    hash: Hex | null;
+}>;
+export type AegisEngineTradeExecutionFailure = ClassifiedError & Readonly<{
+    step: AegisEngineAuthorizationStepKind | null;
+    hash: Hex | null;
+    /**
+     * Last execution boundary observed before this failure.
+     *
+     * `submission` means the wallet transaction request started but returned no
+     * hash. It does not claim that signing completed or that the transaction
+     * reached the network. Optional only so existing v1 consumers that
+     * construct failure fixtures remain source-compatible; sessions created by
+     * this version always publish it.
+     */
+    failurePhase?: 'preparation' | 'wallet-request' | 'submission' | 'confirmation';
+}>;
+export type AegisEngineTradeExecutionRecovery = Readonly<{
+    kind: 'retry-wallet';
+}> | Readonly<{
+    kind: 'switch-network';
+    chainId: number;
+}> | Readonly<{
+    kind: 'review-quote';
+}> | Readonly<{
+    kind: 'view-transaction';
+    hash: Hex;
+}> | Readonly<{
+    kind: 'resume-remaining';
+}> | Readonly<{
+    kind: 'none';
+}>;
+export type AegisEngineAuthorizationReviewReason = Readonly<{
+    kind: 'intent-changed';
+}> | Readonly<{
+    kind: 'wallet-chain-switch-added';
+}> | Readonly<{
+    kind: 'permission-added' | 'permission-changed' | 'unexpected-wallet-request';
+    step: AegisEngineAuthorizationStepKind;
+}>;
+export type AegisEngineTradeQuoteReviewReason = Readonly<{
+    kind: 'intent-changed';
+}> | Readonly<{
+    kind: 'position-availability-changed' | 'swap-route-changed' | 'minimum-output-lower' | 'price-impact-higher' | 'displayed-leverage-changed' | 'opening-ltv-higher' | 'interest-higher' | 'target-return-lower' | 'borrow-limit-lower' | 'liquidation-threshold-lower' | 'utilization-worse-or-missing' | 'runway-shorter' | 'adaptive-fee-evidence-unavailable' | 'adaptive-fee-mode-changed' | 'adaptive-manual-override-changed' | 'adaptive-threshold-lower' | 'adaptive-surge-entered' | 'active-fee-higher';
+}>;
+export type AegisEngineTradeExecutionReview = Readonly<{
+    kind: 'permissions';
+    revision: number;
+    reasons: readonly AegisEngineAuthorizationReviewReason[];
+}> | Readonly<{
+    kind: 'quote';
+    revision: number;
+    reasons: readonly AegisEngineTradeQuoteReviewReason[];
+}>;
+export type AegisEngineTradeExecutionPhase = 'ready' | 'executing' | 'quote-review-required' | 'awaiting-receipt' | 'resume-required' | 'success' | 'failed' | 'cancelled';
+export type AegisEngineTradeExecutionNext = Readonly<{
+    kind: 'continue';
+}> | Readonly<{
+    kind: 'accept-review';
+    revision: number;
+}> | Readonly<{
+    kind: 'check-receipt';
+    hash: Hex;
+}> | Readonly<{
+    kind: 'cancel';
+}> | Readonly<{
+    kind: 'none';
+}>;
+export type AegisEngineTradeExecutionSnapshot = Readonly<{
+    schemaVersion: '1';
+    kind: 'engine-trade-open-execution';
+    sessionId: string;
+    sequence: number;
+    occurredAt: string;
+    chainId: number;
+    quoteRevision: number;
+    phase: AegisEngineTradeExecutionPhase;
+    plan: AegisEngineAuthorizationPlan;
+    quote: AegisEngineTradeOpenQuote;
+    review: AegisEngineTradeExecutionReview | null;
+    next: AegisEngineTradeExecutionNext;
+    steps: readonly AegisEngineTradeExecutionStep[];
+    currentStep: AegisEngineTradeExecutionStep | null;
+    completedPermissions: readonly AegisEngineAuthorizationStepKind[];
+    completedTransactions: readonly Readonly<{
+        kind: AegisEngineAuthorizationStepKind;
+        hash: Hex;
+    }>[];
+    transactionHash: Hex | null;
+    receiptSummary?: AegisEngineTransactionResult['summary'];
+    quoteReviewRequired: boolean;
+    failure: AegisEngineTradeExecutionFailure | null;
+    recovery: AegisEngineTradeExecutionRecovery;
+}>;
+export type AegisEngineTradeExecutionCommand = Readonly<{
+    kind: 'continue';
+}> | Readonly<{
+    kind: 'accept-review';
+    revision: number;
+}> | Readonly<{
+    kind: 'check-receipt';
+}> | Readonly<{
+    kind: 'cancel';
+}>;
+export type AegisEngineTradeOpenExecutionSession = Readonly<{
+    getSnapshot: () => AegisEngineTradeExecutionSnapshot;
+    subscribe: (listener: () => void) => () => void;
+    dispatch: (command: AegisEngineTradeExecutionCommand, options?: Readonly<{
+        signal?: AbortSignal;
+    }>) => Promise<AegisEngineTradeExecutionSnapshot>;
+}>;
+export type AegisEngineTradeOpenExecutionSessionOptions = Readonly<{
+    wallet: Readonly<{
+        provider: Eip1193Provider;
+        account: Address;
+    }>;
+    publicClient: PublicClient;
+    activeChain: AegisSwapChainConfig;
+    intent: AegisEngineTradeOpenIntent;
+    reviewed: Readonly<{
+        plan: AegisEngineAuthorizationPlan;
+        quote: AegisEngineTradeOpenQuote;
+    }>;
+    onTransactionObservation?: (event: AegisTransactionObservation, stage: 'authorization' | 'action') => void;
+    onAuthorizationExecution?: AegisEngineApprovalInput['onAuthorizationExecution'];
+    sessionId?: string;
+    onChange?: (snapshot: AegisEngineTradeExecutionSnapshot) => void;
+}>;
+/** Pure review policy for newly introduced or materially changed wallet authority. */
+export declare function engineAuthorizationPlanReviewReasons(reviewed: AegisEngineAuthorizationPlan, fresh: AegisEngineAuthorizationPlan): readonly AegisEngineAuthorizationReviewReason[];
+/** Pure zero-tolerance policy for weaker or materially different quote facts. */
+export declare function engineTradeQuoteReviewReasons(reviewed: AegisEngineTradeOpenQuote, fresh: AegisEngineTradeOpenQuote): readonly AegisEngineTradeQuoteReviewReason[];
+export declare function createEngineTradeOpenExecutionSession(options: AegisEngineTradeOpenExecutionSessionOptions): AegisEngineTradeOpenExecutionSession;

package/dist/engine/types.d.ts

@@ -1,3 +1,4 @@
+import type { AegisTransactionObservation } from '../swap/receiptWait.js';
 import type { Address, Hex, PublicClient, TransactionReceipt } from 'viem';
 import type { AegisSwapChainConfig, AegisSwapToken } from '../config/index.js';
 import type { SignedPermitBatch } from '../encoding.js';
@@ -30,6 +31,13 @@ export type AegisEngineMarketMetrics = {
     manualOverride?: boolean | null;
     perSwapMode?: boolean | null;
     feeSource?: string | null;
+    /** Post-swap surge-trigger threshold from the opt-in REST v2 market plane.
+     * It is observability data, not a hard price, tick, or slippage limit. */
+    adaptiveTickThresholdTicks?: number;
+    /** Present exactly when adaptiveTickThresholdTicks is present. */
+    adaptiveTickThresholdMode?: 'post_swap_surge_trigger';
+    /** Fee-quote observation time from the opt-in REST v2 market plane. */
+    feeObservedAt?: string | null;
     computedAt?: string | null;
     updatedAt?: string | null;
     engineUpdatedAt?: string | null;
@@ -55,6 +63,7 @@ export type AegisEngineMarket = {
     source: AegisEngineMarketSource;
     status: AegisEngineMarketStatus;
     displayName: string;
+    labels?: string[];
     poolId: Hex;
     token0: AegisEngineToken;
     token1: AegisEngineToken;
@@ -109,6 +118,14 @@ export type AegisEngineMetricPoint = {
     inCapEvent: boolean | null;
     manualOverride: boolean | null;
     perSwapMode: boolean | null;
+    /** Required-nullable on the REST v2 wire; absent only after a 404 fallback
+     * to the frozen v1 history endpoint. */
+    adaptiveTickThresholdTicks?: number | null;
+    /** Paired with adaptiveTickThresholdTicks; describes a post-swap trigger,
+     * never an execution cap. */
+    adaptiveTickThresholdMode?: 'post_swap_surge_trigger' | null;
+    /** Required-nullable on the REST v2 wire; absent after a v1 fallback. */
+    feeObservedAt?: string | null;
     warnings: string[];
 };
 export type AegisEngineMetricHistory = {
@@ -347,8 +364,8 @@ export type AegisEnginePositionActivitySnapshot = {
 /** Off-chain opening intent for one confirmed Long/Short transaction. The
  * Engine transaction does not encode its target scenario or average leverage,
  * so consumers may persist this small record and join it back to the indexed
- * opening transaction. Indexed actions remain authoritative for direction and
- * entry price. */
+ * opening transaction. Indexed actions identify the opening direction; they do not prove an
+ * executed entry price. */
 export type AegisEngineTradePositionIntent = {
     schemaVersion: '1';
     chainId: number;
@@ -367,7 +384,7 @@ export type AegisEngineTradePositionIntent = {
 /** Durable Long/Short identity reconstructed from one vault's indexed opening
  * transaction. Optional scenario fields are present only when a matching
  * off-chain intent record survived; they never override indexed direction or
- * entry price. */
+ * supply execution evidence. */
 export type AegisEngineTradePositionStrategy = {
     kind: 'trade';
     vaultId: string;
@@ -375,8 +392,16 @@ export type AegisEngineTradePositionStrategy = {
     direction: AegisEngineTradeDirection;
     openTxHash: Hex;
     openedAt: number;
-    /** Executed opening spot, token1 per token0, derived from DebtModified. */
+    /** Receipt-reconciled opening swap price in token1 per token0. Indexed
+     * Engine actions alone leave this null; this is not wallet cost basis or PnL. */
     entryPrice: number | null;
+    /** Missing on legacy host records; consumers must treat those as unverified. */
+    entryPriceBasis?: 'receipt-reconciled' | 'unavailable';
+    /** Informational debt-action ratio only. Never substitute it for entryPrice. */
+    referencePrice?: {
+        basis: 'debt-action-token-ratio';
+        price: number | null;
+    };
     /** Reviewed average leverage to the target scenario, not current leverage. */
     averageLeverage: number | null;
     /** Reviewed scenario only. Null when no matching intent record is available. */
@@ -396,6 +421,12 @@ export type AegisEngineBorrowPositionHydration = {
         rL: bigint;
         /** Accrued debt in L units at this hydration frame. */
         debtLLatest: bigint;
+        /** Rounded-up full-range repayment legs at the same verified block.
+         * Null/absent means USD debt and equity must not be estimated from L alone. */
+        debtAmounts?: {
+            amount0: bigint;
+            amount1: bigint;
+        } | null;
         idle0: bigint;
         idle1: bigint;
         /** Null when the vault has no debt, never a synthetic zero. */
@@ -440,6 +471,7 @@ export type AegisEnginePositionsHydrationInput = {
 export type AegisEngineRestSource = {
     kind: 'rest';
     baseUrl: string;
+    includeLabels?: boolean;
     headers?: Record<string, string>;
     /**
      * Maximum time for a shared REST request, including response-body parsing.
@@ -524,6 +556,21 @@ export type AegisEngineReadFrame = {
     /** Local wall-clock time when the frame was assembled, in Unix milliseconds. */
     observedAt: number;
 };
+/** Block-pinned DFM state. The threshold is observed after execution and can
+ * activate or adapt surge fees; it is not an on-chain swap limit. */
+export type AegisEngineAdaptiveFeeEvidence = {
+    source: 'rpc';
+    enforcement: 'post-swap-surge-trigger';
+    evaluationScope: 'per-swap' | 'per-block';
+    blockNumber: bigint;
+    activeFeePpm: number;
+    baseFeePpm: number;
+    surgeFeePpm: number;
+    adaptiveTickThresholdTicks: number;
+    surgeActive: boolean;
+    inCapEvent: boolean;
+    manualOverride: boolean;
+};
 export type AegisEngineVersion = 'v0.4.0' | 'v1.0.2' | 'v1.0.3';
 export type AegisEngineBorrowMarketContext = {
     poolId: Hex;
@@ -587,6 +634,9 @@ export type AegisEngineQuoteBase = {
 };
 export type AegisEngineDepositQuoteInput = AegisEngineQuoteBase & {
     amountIn: bigint;
+    /** Required host policy. A swap quote above this block-pinned impact is
+     *  returned as non-executable; this is independent of output slippage. */
+    maxPriceImpactBps: number;
 };
 /**
  * Live snapshot of an already-open borrow vault, in the pool's real token
@@ -648,7 +698,7 @@ export type AegisEngineBorrowCapacityInput = Omit<AegisEngineQuoteBase, 'owner'
 export type AegisEngineDepositQuoteResult = {
     feasible: boolean;
     executable: boolean;
-    infeasibleReason?: 'invalid-input' | 'quote-unavailable' | 'insufficient-output' | 'zero-liquidity' | 'builder-error';
+    infeasibleReason?: 'invalid-input' | 'quote-unavailable' | 'price-impact-unavailable' | 'price-impact-limit' | 'insufficient-output' | 'zero-liquidity' | 'builder-error';
     /** SDK recipe input retained for diagnostics. Use `tx` on the enclosing
      * Core quote for execution instead of encoding this value downstream. */
     encodeInput: unknown | null;
@@ -706,6 +756,9 @@ export type AegisEngineDepositQuote = {
     kind: 'lend';
     market: AegisEngineMarket;
     inputToken: AegisEngineToken;
+    /** Same-block DFM evidence when the trusted RPC read succeeded. Null means
+     *  the quote carries no adaptive-fee observation, never a zero threshold. */
+    adaptiveFee?: AegisEngineAdaptiveFeeEvidence | null;
     quote: AegisEngineDepositQuoteResult;
     tx: AegisEnginePreparedTransaction | null;
 };
@@ -805,12 +858,28 @@ export type AegisEngineTradeOpenQuoteInput = {
     /** @deprecated Ignored. Spec-0168 always selects the lower-debt frontier. */
     rootPolicy?: AegisEngineTapRootPolicy;
     slippageBps: number;
+    /** Required host policy. Core rejects a block-pinned internal swap whose
+     *  price impact exceeds this value. It is not a pool-movement invariant. */
+    maxPriceImpactBps: number;
     deadline?: bigint;
     /** Abort a superseded indicative quote between its block-pinned phases. */
     signal?: AbortSignal;
     /** Submit paths set this after changing router authorization. */
     forceExecutionEvidenceRefresh?: boolean;
 };
+/** Exact caller-owned strategy and safety policy that produced a Trade quote.
+ * Execution sessions bind this echo before any wallet request. */
+export type AegisEngineTradeOpenQuoteIntent = Readonly<{
+    owner: Address;
+    inputIsToken0: boolean;
+    collateralIn: bigint;
+    /** Null means the quote selected the live maximum. */
+    leverage: number | null;
+    horizonSeconds: number;
+    priceMove: number;
+    slippageBps: number;
+    maxPriceImpactBps: number;
+}>;
 export type AegisEngineTradeOpenInfeasibleReason = AegisEngineTapInfeasibleReason['kind']
 /** The chosen root's swap trades against the requested direction at entry. */
  | 'swap-direction-mismatch'
@@ -821,7 +890,11 @@ export type AegisEngineTradeOpenInfeasibleReason = AegisEngineTapInfeasibleReaso
 /** LTV recomputed from the encoded amounts is at or above the open cap. */
  | 'ltv-above-max'
 /** The swap was quoted at a different block than the sizing state. */
- | 'stale-frame';
+ | 'stale-frame'
+/** The block-pinned quote could not produce a finite impact assessment. */
+ | 'price-impact-unavailable'
+/** The block-pinned quote exceeded the host's required impact limit. */
+ | 'price-impact-limit';
 /** Actionable bounds for a rejected quote. Each field is null when the
  *  rejection did not produce one. */
 export type AegisEngineTradeOpenLimits = {
@@ -867,8 +940,25 @@ export type AegisEngineTradeOpenPosition = {
     /** Gross return from exact entry equity to target equity, before horizon
      *  interest. The encoded swap output floor is already reflected in both. */
     grossReturnAtTargetPct: number;
+    /** Indicative equity at the reviewed prices, in token1 major units. Uses
+     * the quote rate held constant; excludes gas and future closing costs. */
+    scenario?: {
+        entryEquity: number;
+        targetEquityAfterInterest: number;
+        targetInterest: number;
+    };
     /** Borrow principal in rL units. */
     principalDeltaRl: bigint;
+    /**
+     * Market utilization immediately before and after this position's final,
+     * integer-rounded debt is added. Both values come from the quote's pinned
+     * market frame; consumers must not mix in a REST utilization snapshot.
+     */
+    marketUtilization?: {
+        beforePips: number;
+        afterPips: number;
+        capPips?: number;
+    };
     /** Vault idle at lock, in base units — the collateral `lockVault` values. */
     collateral0: bigint;
     collateral1: bigint;
@@ -894,6 +984,8 @@ export type AegisEngineTradeOpenQuote = {
     market: AegisEngineMarket;
     direction: AegisEngineTradeDirection;
     collateralToken: AegisEngineToken;
+    /** Exact request identity used to build this quote. */
+    intent: AegisEngineTradeOpenQuoteIntent;
     /** Thresholds read in the same live frame used to size the position. */
     thresholds: {
         maxLtvPips: number;
@@ -908,6 +1000,8 @@ export type AegisEngineTradeOpenQuote = {
     position: AegisEngineTradeOpenPosition | null;
     /** Null when the borrow already delivers the target mix. */
     swap: AegisEngineTradeOpenSwap | null;
+    /** Same-block DFM evidence. This is review telemetry, not an execution cap. */
+    adaptiveFee?: AegisEngineAdaptiveFeeEvidence | null;
     deposit: {
         amount0: bigint;
         amount1: bigint;
@@ -974,6 +1068,13 @@ export type AegisEnginePositionActionQuote = {
     } | null;
     /** Borrow principal affected by repay/close, in rL units. */
     principalDeltaRl: bigint | null;
+    requestedRepayProjection?: {
+        ltvPips: number | null;
+        debtFree: boolean;
+        idle0: bigint;
+        idle1: bigint;
+        debtL: bigint;
+    } | null;
     /** Exact idle token amounts requested by withdraw. */
     withdraw: {
         amount0: bigint;
@@ -1012,6 +1113,8 @@ type AegisEnginePositionActionQuoteBase = {
     signal?: AbortSignal;
 };
 export type AegisEngineRepayQuoteInput = AegisEnginePositionActionQuoteBase & {
+    /** Opt into a recent canonical frame (0–60 seconds); omitted keeps strict current-head verification. */
+    executionFrameMaxAgeSeconds?: bigint;
     target: AegisEngineBorrowPositionTarget;
     repayRl?: bigint | 'full';
     slippageBps: number;
@@ -1025,6 +1128,8 @@ export type AegisEngineAddCollateralQuoteInput = AegisEngineQuoteBase & {
     forceExecutionEvidenceRefresh?: boolean;
 };
 export type AegisEngineCloseQuoteInput = AegisEnginePositionActionQuoteBase & {
+    /** Opt into a recent canonical frame (0–60 seconds); omitted keeps strict current-head verification. */
+    executionFrameMaxAgeSeconds?: bigint;
     target: AegisEngineBorrowPositionTarget;
 };
 export type AegisEngineIdleWithdrawQuoteInput = AegisEnginePositionActionQuoteBase & {
@@ -1211,7 +1316,10 @@ export type AegisEnginePreparedTransaction = {
 export type AegisEngineSignedPermitBatch = SignedPermitBatch;
 export type AegisEngineWalletSession = WalletSession;
 export type AegisEngineActionCallbacks = {
+    onTransactionObservation?: (event: AegisTransactionObservation) => void;
     onStatus?: (status: 'approving' | 'signing' | 'submitting' | 'success' | 'idle') => void;
+    /** Fires after simulation and chain guards, immediately before the wallet request. */
+    onWalletRequest?: () => void;
     onTxHash?: (hash: Hex | null) => void;
     onSubmitted?: (hash: Hex) => void;
 };
@@ -1235,8 +1343,11 @@ export type AegisEngineAuthorizationStep = {
     id: AegisEngineAuthorizationStepKind;
     kind: AegisEngineAuthorizationStepKind;
     status: AegisEngineAuthorizationStepStatus;
-    /** Every current Long/Short authorization is an on-chain wallet transaction. */
-    walletAction: 'transaction';
+    /**
+     * Wallet interaction required by this step. Permit2 signature mode can fall
+     * back to an on-chain spending-cap transaction when typed data is unavailable.
+     */
+    walletAction: 'transaction' | 'signature-or-transaction';
     /** Contract the wallet action targets. */
     target: Address;
     /** Contract receiving authority, when distinct from the target. */
@@ -1245,6 +1356,7 @@ export type AegisEngineAuthorizationStep = {
     token: AegisEngineToken | null;
     /** Current on-chain allowance, when the step governs a token amount. */
     currentAmount: bigint | null;
+    currentExpiration?: number | null;
     /** Amount a required wallet action will set. Null for satisfied or non-token actions. */
     requestedAmount: bigint | null;
     /** Permit2 expiry in Unix seconds. Null when the authority has no expiry field. */
@@ -1277,7 +1389,7 @@ export type AegisEngineAuthorizationPlan = {
     missingPermissionCount: number;
     /** True when the known wallet chain adds a network-switch request; null when unknown. */
     walletChainSwitchRequired: boolean | null;
-    /** Sequential transaction request count. A network switch is reported separately. */
+    /** Sequential wallet-action count. A network switch is reported separately. */
     walletPromptCount: number;
     /** True when only the final position transaction remains. */
     readyForOpen: boolean;
@@ -1292,12 +1404,16 @@ export type AegisEngineAuthorizationPlanInput = {
     token: AegisEngineToken;
     amount: bigint;
     approvalMode?: 'exact' | 'max';
+    /** Must match the authorization mode used when the reviewed plan is executed. */
+    permit2AuthorizationMode?: 'signature' | 'spending-cap';
 };
 export type AegisEngineAuthorizationProgress = {
     kind: AegisEngineAuthorizationStepKind;
     status: 'requesting' | 'confirmed';
 };
-/** Lifecycle evidence for one Engine permission request. */
+/** Truthful per-prerequisite lifecycle. Kept separate from the legacy
+ * requesting/confirmed projection so existing exhaustive consumers do not
+ * break when submitted and terminal states are added. */
 export type AegisEngineAuthorizationExecutionEvent = Readonly<{
     kind: AegisEngineAuthorizationStepKind;
     status: 'wallet-requested';
@@ -1306,13 +1422,15 @@ export type AegisEngineAuthorizationExecutionEvent = Readonly<{
     kind: AegisEngineAuthorizationStepKind;
     status: 'submitted';
     hash: Hex;
+    replacesHash?: Hex;
+    executionChanged?: boolean;
 }> | Readonly<{
     kind: AegisEngineAuthorizationStepKind;
     status: 'confirmed';
     hash: Hex | null;
 }> | Readonly<{
     kind: AegisEngineAuthorizationStepKind;
-    status: 'cancelled' | 'failed';
+    status: 'failed' | 'cancelled';
     hash: Hex | null;
     error: ClassifiedError;
 }>;
@@ -1320,9 +1438,9 @@ export type AegisEngineApprovalInput = {
     wallet: AegisEngineWalletSession;
     publicClient: PublicClient;
     activeChain: AegisSwapChainConfig;
+    /** Reviewed market used to resolve Permit2 and router from the trusted registry. */
+    market: AegisEngineMarket;
     token: AegisEngineToken;
-    permit2: Address;
-    router: Address;
     amount: bigint;
     approvalMode?: 'exact' | 'max';
     permit2AuthorizationMode?: 'signature' | 'spending-cap';
@@ -1331,7 +1449,7 @@ export type AegisEngineApprovalInput = {
     onStatus?: AegisEngineActionCallbacks['onStatus'];
     /** Fine-grained prerequisite progress for truthful wallet onboarding. */
     onAuthorizationProgress?: (progress: AegisEngineAuthorizationProgress) => void;
-    /** Full prerequisite lifecycle at the wallet and receipt boundaries. */
+    /** Full prerequisite lifecycle at the real wallet and receipt boundaries. */
     onAuthorizationExecution?: (event: AegisEngineAuthorizationExecutionEvent) => void;
     /** Awaited after each prerequisite receipt and before another wallet request. */
     onAuthorizationCheckpoint?: () => Promise<void>;

package/dist/engine/v4Quote.d.ts

@@ -0,0 +1,5 @@
+export type AegisEngineV4ExactInputFrameQuote = Readonly<{
+    amountOut: bigint;
+    gasEstimate: bigint;
+    blockNumber: bigint;
+}>;