@aegis-engine/core 0.4.0 → 0.5.0

package/README.md

@@ -31,8 +31,9 @@ the published Core package; consumers do not need GitHub Packages credentials.
   bounded session caches, and explicit indexed freshness.
 - Engine 12-hour market-metric history for optional rate, utilization, and
   liquidity charts.
-- Engine lend and borrow quotes, exact rounded LP-shaped debt/carry
-  projections, collateral sizing, Permit2 preparation, and guarded execution.
+- Engine lend, borrow, and directional Long/Short quotes; exact rounded
+  LP-shaped debt/carry projections; collateral sizing; Permit2 preparation;
+  and guarded execution.
 
 Direct pool swaps support `exactIn` and `exactOut`. KyberSwap routes currently
 support `exactIn` only because Kyber's route/build flow is exact-input.
@@ -46,8 +47,10 @@ Engine discovery and wallet positions default to partner-safe REST:
 
 ```ts
 import {
+  deriveEngineTradePositionStrategy,
   fetchEngineMarketHistory,
   fetchEngineMarkets,
+  fetchEnginePositionActivitySnapshot,
   fetchEnginePositionsSnapshot
 } from '@aegis-engine/core'
 
@@ -63,6 +66,16 @@ const positions = await fetchEnginePositionsSnapshot({
   chainId: 1,
   account
 })
+const activity = await fetchEnginePositionActivitySnapshot({
+  source,
+  chainId: 1,
+  account
+})
+const position = positions.positions[0]
+const vault = activity?.vaults.find((entry) => entry.vaultId === position?.vaultId)
+const strategy = position && vault
+  ? deriveEngineTradePositionStrategy(position, vault)
+  : null
 const marketHistory = await fetchEngineMarketHistory({
   source,
   marketId: markets[0].id,
@@ -71,7 +84,10 @@ const marketHistory = await fetchEngineMarketHistory({
 ```
 
 Hosts that already own deterministic market/position metadata can instead use
-the typed `static` source. Engine market history remains a REST capability.
+the typed `static` source. Supply `vaultActivity` when an offline fixture must
+reconstruct Long/Short identity; position rows alone are ordinary borrow-vault
+facts and are not enough to classify a trade. Engine market history remains a
+REST capability.
 
 The REST service supplies facts and provenance. Core owns live RPC reads,
 collateral/debt math, quote freshness, recipe construction, simulation,
@@ -106,6 +122,76 @@ remaining collateral stays in the vault until a separate withdrawal. A
 one-token lend is a zap into a two-sided full-range LP, not single-token
 lending.
 
+### Directional Engine positions
+
+`quoteEngineTradeOpen` sizes a fresh-vault Long or Short against one
+block-pinned Engine and Uniswap v4 frame. It returns the selected average and
+live leverage, exact opening LTV after the swap minimum, interest carry, risk
+thresholds, gross return at the configured target, actionable solver limits,
+and atomic router calldata when all execution gates pass.
+
+Successful and leverage-bound quotes expose `limits.minLeverage` and
+`limits.maxLeverage`. Treat these as live, request-specific bounds rather than
+a protocol-wide constant.
+
+`deriveEngineTradePositionStrategy` recognizes the indexed Tap opening action
+shape and recovers its Long/Short direction and executed entry price after a
+reload. The selected target and average-to-target leverage are not transaction
+fields. A host can pass persisted intent records to augment those fields only
+when chain, account, market, pool, transaction, and direction all match.
+A no-swap opening has no indexed direction signal, so this helper deliberately
+leaves it unclassified instead of trusting off-chain intent alone.
+
+```ts
+import { quoteEngineTradeOpen } from '@aegis-engine/core'
+
+const quote = await quoteEngineTradeOpen({
+  publicClient,
+  market,
+  owner: account,
+  direction: 'long',
+  collateralIn: 1_000_000n,
+  inputIsToken0: false,
+  leverage: 1.5,
+  horizonSeconds: 30 * 24 * 60 * 60,
+  priceMove: 0.2,
+  slippageBps: 100
+})
+```
+
+Treat `feasible` and `executable` separately. A feasible quote can still need
+the trusted router's vault-operator grant or Permit2 authorization. After an
+authorization transaction, request the submit quote with
+`forceExecutionEvidenceRefresh: true`; then pass its fresh `tx` and `expiresAt`
+to `sendEngineTransaction`. The prebuilt `AegisLeverageWidget` performs this
+sequence for frontend integrations.
+
+Use `readEngineAuthorizationPlan` to present the connected account's current
+wallet sequence before submission:
+
+```ts
+import { readEngineAuthorizationPlan } from '@aegis-engine/core'
+
+const plan = await readEngineAuthorizationPlan({
+  publicClient,
+  market,
+  owner: account,
+  walletChainId,
+  token: market.token0,
+  amount: 1_000_000n,
+  approvalMode: 'exact'
+})
+```
+
+`missingPermissionCount` excludes the final open and any zero-first reset.
+`walletPromptCount` includes every required sequential transaction.
+`walletChainSwitchRequired` reports the network switch separately and is null
+until the wallet chain is known. The plan is a read-only presentation snapshot, not authorization
+evidence. Submission must still re-read permissions and obtain a fresh
+executable quote. Exact ERC-20 and Permit2 limits are consumed by the successful
+opening transfer; maximum limits and the VaultRegistry operator grant remain
+active until revoked.
+
 ## Historical token prices
 
 Historical prices are intentionally separate from Engine market and
@@ -113,10 +199,7 @@ transaction truth. A host reads one exact token through the public REST
 backend without placing private data-service credentials in the client:
 
 ```ts
-import {
-  AEGIS_BACKEND_PROD_BASE_URL,
-  fetchTokenPriceHistory
-} from '@aegis-engine/core'
+import { AEGIS_BACKEND_PROD_BASE_URL, fetchTokenPriceHistory } from '@aegis-engine/core'
 
 const history = await fetchTokenPriceHistory({
   baseUrl: AEGIS_BACKEND_PROD_BASE_URL,
@@ -189,10 +272,7 @@ const wallet = await resolveWalletSession({
 Create a read-side viem client from an Aegis chain config:
 
 ```ts
-import {
-  AEGIS_SWAP_MAINNET_CHAIN,
-  createSwapPublicClient
-} from '@aegis-engine/core'
+import { AEGIS_SWAP_MAINNET_CHAIN, createSwapPublicClient } from '@aegis-engine/core'
 
 const publicClient = createSwapPublicClient(
   AEGIS_SWAP_MAINNET_CHAIN.chain,
@@ -212,10 +292,7 @@ metadata, market discovery, allowlists, and fee policy come from REST. Swap
 execution remains client-side.
 
 ```ts
-import {
-  AEGIS_BACKEND_PROD_BASE_URL,
-  createAegisBackendApiClient
-} from '@aegis-engine/core'
+import { AEGIS_BACKEND_PROD_BASE_URL, createAegisBackendApiClient } from '@aegis-engine/core'
 
 const aegisApi = createAegisBackendApiClient({
   baseUrl: AEGIS_BACKEND_PROD_BASE_URL
@@ -281,10 +358,7 @@ provided, core verifies it matches the key.
 ## Direct Pool Quote
 
 ```ts
-import {
-  AEGIS_SWAP_MAINNET_CHAIN,
-  fetchDirectPoolSwapQuote
-} from '@aegis-engine/core'
+import { AEGIS_SWAP_MAINNET_CHAIN, fetchDirectPoolSwapQuote } from '@aegis-engine/core'
 
 const quote = await fetchDirectPoolSwapQuote({
   publicClient,
@@ -339,10 +413,7 @@ protection the user saw.
 ## KyberSwap Quote
 
 ```ts
-import {
-  AGGREGATED_SWAP_DEFAULT_TOKENS,
-  fetchAggregatedSwapQuote
-} from '@aegis-engine/core'
+import { AGGREGATED_SWAP_DEFAULT_TOKENS, fetchAggregatedSwapQuote } from '@aegis-engine/core'
 
 const quote = await fetchAggregatedSwapQuote(
   AGGREGATED_SWAP_DEFAULT_TOKENS.USDC,

package/THIRD_PARTY_NOTICES.md

@@ -2,7 +2,7 @@
 
 The lazy Engine implementation includes code from these MIT-licensed works:
 
-- `@labs-solo/aegis-engine-sdk` 0.30.0 — Copyright (c) 2026 Solo Labs
+- `@labs-solo/aegis-engine-sdk` 0.33.0 — Copyright (c) 2026 Solo Labs
 - `@uniswap/sdk-core` 6.1.1 and 7.18.0 — Copyright (c) 2021 Uniswap Labs
 - `@uniswap/v3-sdk` 3.27.0 — Copyright (c) 2021 Uniswap Labs
 - `tiny-invariant` 1.3.3 — Copyright (c) 2019 Alexander Reardon