@aegis-engine/core 0.6.0 → 0.8.0

package/README.md

@@ -1,5 +1,12 @@
 # Aegis Core
 
+Direct paired lending is exposed by `quoteEngineBalancedDeposit` and
+`executeEngineBalancedDeposit`, with a discriminated `AegisEngineLendIntent`.
+The quote preserves both token limits, protected shares, funding, native reserve,
+and frame evidence. Execution reuses the Engine approval and receipt flow.
+See [the integration guide](../../docs/balanced-lending.md) for the required SDK
+release dependency, reviewed-bound behavior and verification limits.
+
 React-free Swap and Engine operations for Aegis integrations.
 
 `@aegis-engine/core` is the operations layer behind the Aegis swap experience.
@@ -17,6 +24,25 @@ npm install @aegis-engine/core viem
 RPC setup. The protocol implementation used by Engine quotes is bundled into
 the published Core package; consumers do not need GitHub Packages credentials.
 
+For account data without the execution layer, import from
+`@aegis-engine/core/account`. This entry includes portfolio/activity reads,
+`fetchEnginePositionHistory`, `fetchEngineHistoryPositions` (including closed
+positions), and `createEngineTransactionHistory` for scoped metadata and
+receipt-only recovery. It imports no React, Widget CSS or execution SDK chunk.
+`fetchEnginePositionAccounting` adds immutable raw accounting pages, proven
+ownership when available, and separate financial-completeness flags. Continue
+with `nextCursor`; do not treat raw event availability as executed prices or
+wallet PnL. The widget hooks entry exports `useEnginePositionAccounting` for
+explicit reads and refreshes without background polling.
+History retains missing observations and unknown valuations; page totals must
+not be added together. The endpoints require a backend that serves the pinned
+account/history contract.
+
+Installed-package checks use the configured Node runtime, strict TypeScript 5.8 NodeNext and
+Bundler, and TypeScript 5.6 Bundler. Current viem types require TypeScript 5.8+
+for NodeNext. See the repository's `docs/package-data-contracts.md` for the
+exact compatibility matrix, storage and coverage semantics, and release gates.
+
 ## What It Supports
 
 - Direct Aegis pool quotes and execution against host-supplied Uniswap v4 pool
@@ -89,6 +115,11 @@ 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.
 
+`readEngineVaultActivity` is a separate best-effort helper that queries the
+public Engine subgraph. A browser caller sends the chain and vault identifier
+to that indexer. Do not call it for a fully offline integration; provide the
+static `vaultActivity` fixture instead.
+
 The REST service supplies facts and provenance. Core owns live RPC reads,
 collateral/debt math, quote freshness, recipe construction, simulation,
 approval, and send. `positions.freshness` is indexed provenance:
@@ -178,6 +209,12 @@ 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.
 
+Every Lend or Trade quote with an internal swap requires
+`maxPriceImpactBps`. Core derives the impact from that same block-pinned quote
+and returns a typed, non-executable `price-impact-limit` or
+`price-impact-unavailable` result when it cannot satisfy the host policy.
+This is an SDK execution gate. It is not a Router-level pool-price invariant.
+
 Successful and leverage-bound quotes expose `limits.minLeverage` and
 `limits.maxLeverage`. Treat these as live, request-specific bounds rather than
 a protocol-wide constant.
@@ -203,16 +240,16 @@ const quote = await quoteEngineTradeOpen({
   leverage: 1.5,
   horizonSeconds: 30 * 24 * 60 * 60,
   priceMove: 0.2,
-  slippageBps: 100
+  slippageBps: 100,
+  maxPriceImpactBps: 500
 })
 ```
 
 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.
+the trusted router's vault-operator grant or Permit2 authorization. The
+low-level quote, authorization, and send functions remain available as
+primitives. For a reviewed Long/Short flow, prefer the execution session below
+so every integration uses the same re-planning and receipt-recovery rules.
 
 Use `readEngineAuthorizationPlan` to present the connected account's current
 wallet sequence before submission:
@@ -232,7 +269,9 @@ const plan = await readEngineAuthorizationPlan({
 ```
 
 `missingPermissionCount` excludes the final open and any zero-first reset.
-`walletPromptCount` includes every required sequential transaction.
+`walletPromptCount` includes every required sequential wallet action. In
+Permit2 signature mode, the Permit2 router step can be a typed-data signature
+or a fallback spending-cap 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
@@ -240,6 +279,55 @@ 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.
 
+### Reviewed trade execution
+
+`createEngineTradeOpenExecutionSession` is the React-free execution boundary
+for partner UIs. Give it the wallet, the exact intent the user reviewed, and
+the matching plan and quote. Core then re-reads permissions before every wallet
+request, re-quotes from a fresh block-pinned frame after permissions settle,
+and stops for review if authority or execution facts become less favorable.
+
+```ts
+import { createEngineTradeOpenExecutionSession } from '@aegis-engine/core'
+
+const session = createEngineTradeOpenExecutionSession({
+  wallet,
+  publicClient,
+  activeChain,
+  intent: {
+    owner: wallet.account,
+    market,
+    direction: 'long',
+    token: market.token0,
+    amount: 1_000_000n,
+    leverage: 1.5,
+    horizonSeconds: 30 * 24 * 60 * 60,
+    priceMove: 0.2,
+    slippageBps: 100,
+    maxPriceImpactBps: 500,
+    approvalMode: 'exact'
+  },
+  reviewed: { plan, quote },
+  onChange: renderExecution
+})
+
+await session.dispatch({ kind: 'continue' })
+```
+
+Read `session.getSnapshot().next` before each user action:
+
+- `continue`: continue the reviewed flow.
+- `accept-review`: show `snapshot.review`, then dispatch the exact `revision`
+  after the user accepts the updated plan or quote.
+- `check-receipt`: check the retained transaction hash without broadcasting.
+- `cancel`: stop preparation before a transaction hash exists.
+- `none`: no command is currently safe or necessary.
+
+A wallet rejection stops before chain confirmation. A receipt timeout retains
+the submitted hash and permits only `check-receipt`; it never enables a blind
+retry. If a prerequisite confirms late, the session returns
+`resume-required`, so the next wallet request still needs an explicit Continue.
+
 ## Historical token prices
 
 Historical prices are intentionally separate from Engine market and
@@ -582,3 +670,140 @@ concurrent package publishes from rebuilding shared workspace artifacts.
 pnpm build
 pnpm pack:check
 ```
+
+## Engine account portfolio and activity
+
+`fetchEngineAccountPortfolio({ source, account, chainIds, signal })` reads one complete, bounded account snapshot from the versioned portfolio API. The returned positions, totals, prices and per-chain frames belong to the same snapshot. A failed or expired page rejects the read instead of mixing snapshots. Supported chain IDs are 1, 130, 8453 and 4663; pass the distinct host-selected set.
+
+Metrics keep `usd: null`, a `knownUsd` subtotal and reasons when coverage is incomplete. Gross assets include supplied value; adding supply again would double count it. Debt and net equity remain separate. NFT principal, fees, unknown prices and unavailable chains retain their coverage reasons. `performance` explicitly reports unavailable cash-flow and cost-basis evidence.
+
+`fetchEngineAccountActivity` reads one continuation page, and `groupEngineAccountActivity` joins events by chain and transaction while preserving vault-balance changes separately from lending settlement. `formatEngineAccountTokenAmount` formats raw bigint strings using verified decimals, without a Number round-trip or an assumed 18-decimal fallback. Indexed events are not receipt finality.
+
+`fetchEngineTransactionStatus` consumes the backend receipt/indexer/portfolio acknowledgement. A `ready` result must include a checked receipt, the complete event acknowledgement, and an unexpired portfolio at or beyond its block. This is checked-at-read evidence, not a finalized transaction or permission to submit it again.
+
+`resolveEngineAccountPositionTarget` maps a portfolio identity to the existing position manager only with matching account, chain, pool, Engine, registry and recent successful live hydration. The target keeps the legacy live position ID; the aggregate API ID is never substituted into an unrelated action context.
+
+Safe transaction-history helpers expose versioned, wallet/chain-scoped display metadata and hashes. They reject extra executable fields and retain pending identities when completed history is pruned. They do not persist quotes, signatures, permits or transaction calldata.
+
+`onTransactionObservation` on Engine and swap executors reports the submitted hash, replacement relationship and receipt outcome without executable data. `executionChanged` distinguishes a price-only speed-up from a replacement that changed the call; receipt recovery retains that evidence through timeouts. Approval helpers report and return the hash that actually mines. Transaction-history merges retain replacement ancestry across out-of-order observations and keep authorization records distinct from position actions.
+
+`deriveEngineTradePositionStrategy` identifies a Tap opening from indexed Engine
+activity, but leaves `entryPrice: null` and `entryPriceBasis: 'unavailable'`.
+Its optional `referencePrice` is the debt-action token ratio, which excludes the
+actual swap's price impact and fees. It must not become entry price or cost basis.
+The widget accepts entry-based display only with an explicit
+`entryPriceBasis: 'receipt-reconciled'`. Legacy host records without that basis
+remain unverified. Receipt ingestion is a separate consumer integration; this
+change does not claim it is already available through the accounting endpoint.
+
+### Market series
+
+`fetchEngineMarketCandles`, `fetchEngineMarketReferenceHistory`, and
+`fetchEngineRateHistory` read public market data with a shared, bounded REST request.
+Validated responses are cached for 30 seconds with at most 16 entries, keyed by
+endpoint, request headers, timeout, market, series and window. A missing endpoint
+backs off for 60 seconds; 429/503 responses back off for at least 30 seconds and
+honor a longer `Retry-After`. `AegisEngineMarketDataReadError.retryAfterSeconds`
+exposes the retry delay. Reads never start automatic polling or switch sources.
+
+Each consumer receives its own snapshot and can abort its wait independently;
+the shared transport retains its response-size limit and deadline. Use
+`clearEngineMarketSeriesCache()` for an explicit host reset. Cached history is
+display evidence, never a fresh quote or an execution prerequisite.
+
+```ts
+import {
+  fetchEngineMarketCandles,
+  fetchEngineMarketReferenceHistory,
+  fetchEngineRateHistory,
+  splitEngineMarketCandleSegments
+} from '@aegis-engine/core'
+
+const input = { source: { kind: 'rest' as const, baseUrl }, marketId, signal }
+const candles = await fetchEngineMarketCandles({
+  ...input,
+  window: '1d',
+  expectedAssets: { baseAsset: market.token0, quoteAsset: market.token1 }
+})
+const segments = splitEngineMarketCandleSegments(candles)
+// Plot each segment on the same requestedFrom/requestedTo time axis.
+const reference = await fetchEngineMarketReferenceHistory({ ...input, window: '7d' })
+const rates = await fetchEngineRateHistory({ ...input, window: '30d' })
+```
+
+Pool history provides OHLC and distinguishes exact five-minute swaps from
+upstream hourly/daily pool aggregates. Aggregate `txCount` is not a swap count.
+`expectedAssets` checks selected token addresses and decimals, including cache
+hits. `splitEngineMarketCandleSegments` retains valid candles on both sides of
+explicit gaps. It does not fill quiet buckets, synthesize one-second rows, or
+turn a current pool-state reference into historical OHLC.
+The explicitly requested reference is a line of token USD close ratios, with
+bucket-only synchronization and unknown historical venue independence. It is
+neither pair OHLC nor independent fair value. Neither series is execution price,
+cost basis, or a transaction quote. Reference history has no one-day window.
+
+Rate history exposes simple lending APR estimates and borrow rates. Coverage and
+canonical provenance are separate: a complete legacy series can be `ready` while
+its observations remain `legacy-unpinned`. Missing buckets and missing rate
+values remain explicit. Observation checks do not claim finality or realized PnL.
+
+The market-data OpenAPI snapshot has its own exact backend revision because its
+PR is independent of the position-accounting stack. Both snapshots are checked
+by `openapi:parity` and the live release gate. Generated types and runtime guards
+are local source contracts; endpoint deployment and new writer observations
+still require separate qualification.
+
+### Completed tap trade token PnL
+
+`fetchEnginePositionPnl` is available through `@aegis-engine/core/account`.
+Pass the `snapshotId` from `fetchEnginePositionAccounting` for the same account,
+chain, pool and vault. It makes one bounded API request; it does not refresh the
+accounting snapshot, read prices or poll.
+
+```ts
+import { fetchEnginePositionPnl } from '@aegis-engine/core/account'
+
+const pnl = await fetchEnginePositionPnl({
+  source: { kind: 'rest', baseUrl: backendUrl },
+  account, chainId, poolId, vaultId,
+  snapshotId: accounting.snapshotId,
+  signal
+})
+if (pnl.status === 'token-pnl') {
+  // Each currency keeps its own raw units. Do not sum these token amounts.
+  renderTokenPnl(pnl.key.currency0, pnl.totals.net.amount0Raw)
+  renderTokenPnl(pnl.key.currency1, pnl.totals.net.amount1Raw)
+}
+```
+
+The backend supports one-owner, NFT-free ERC20 tap trades from opening through a
+supported full vault close. Other histories return an explicit unavailable
+reason. Paid, received and net amounts are validated independently. Trading and
+borrowing charges are embedded in those flows; execution gas is a separate
+native-wei amount. Historical USD PnL, approval costs, L2/data fees and total
+economic PnL remain unavailable. Label the result as token PnL; a token gain and
+a loss in another currency are not a single profit percentage.
+
+Responses retain capture-time provenance and expiry, not a finality guarantee.
+An expired snapshot yields 410 and requires an explicit accounting refresh.
+The API must publish/pin the settlement SDK and deploy the additive PnL endpoint
+before this read is available. The matching maintained fixture in
+`scripts/fixtures/package-consumers/position-pnl-v1.json` was produced by the
+SDK receipt reconciler and API adapter, then accepted unchanged by this reader.
+
+## Borrow collateral sizing
+
+`quoteEngineBorrowCapacity` reports `collateralFloor` as a settled result:
+`not-requested`, `ready-positive`, `ready-zero`, `infeasible`, or `unavailable`.
+Unavailable results include a reason and whether a fresh read may help. A null
+closed-form result is terminal for that request; it does not mean the request is
+still running. Zero means no additional collateral is needed at the sizing
+inputs; it is not permission to submit a new borrow. Its `outputSource`
+distinguishes existing idle tokens from new debt or an unknown legacy result.
+Only confirmed idle output supports a withdrawal review through the normal
+protected quote and authorization flow.
+`minimumNoSwapCollateralIn` remains available for compatibility, and
+`resolveEngineBorrowCollateralFloor` adapts older capacity snapshots.
+
+The result's `frame` identifies the market read used for sizing. Caller-supplied
+vault inputs and any executable transaction still require fresh validation.

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.33.0 — Copyright (c) 2026 Solo Labs
+- `@labs-solo/aegis-engine-sdk` 0.40.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

package/dist/account.d.ts

@@ -0,0 +1,11 @@
+/** Account reads and transaction metadata without wallet execution or React. */
+export * from './engine/account/types.js';
+export * from './engine/account/client.js';
+export * from './engine/account/history.js';
+export * from './engine/account/accounting.js';
+export * from './engine/account/positionPnl.js';
+export * from './engine/account/positionPerformance.js';
+export * from './engine/account/activity.js';
+export * from './engine/account/management.js';
+export * from './engine/account/transactions.js';
+export * from './engine/account/transactionHistory.js';

package/dist/account.js

@@ -0,0 +1,129 @@
+import { w as u, o as b, n as A, s as I, l as P, E as g, A as h, r as f, a as x, i as c, b as E, c as S, d as C, e as _, P as T, f as D } from "./transactionHistory-1Zl2KCcV.js";
+import { g as M, h as j, j as J, k as O, m as U, p as G, q as Z, t as Q, u as V, v as W, x as X, y as Y, z as ee, B as ae, C as oe, D as se, F as ne, G as te, H as re } from "./transactionHistory-1Zl2KCcV.js";
+import { keccak256 as k, encodeAbiParameters as y } from "viem";
+const H = b({ version: P(1), snapshotId: I().uuid(), page: A().int().min(1).max(95) }).strict();
+function v(e) {
+  if (!/^[A-Za-z0-9_-]{1,256}$/.test(e)) throw new Error("invalid-cursor");
+  return H.parse(JSON.parse(atob(e.replace(/-/g, "+").replace(/_/g, "/"))));
+}
+function L(e) {
+  return u({ ...e, chainIds: [e.chainId] }, async (r) => {
+    let o;
+    try {
+      if (!/^0x[0-9a-fA-F]{64}$/.test(e.poolId) || !["lend_shares", "borrow_vault"].includes(e.kind) || (e.kind === "borrow_vault" ? !g.safeParse(e.vaultId).success : e.vaultId !== void 0)) throw new Error("invalid-query");
+      e.cursor !== void 0 && (o = v(e.cursor));
+    } catch {
+      throw new h("invalid-query", 400);
+    }
+    const a = await f(r, "positions/accounting", {
+      chainId: String(e.chainId),
+      poolId: e.poolId.toLowerCase(),
+      kind: e.kind,
+      ...e.kind === "borrow_vault" ? { vaultId: e.vaultId } : {},
+      ...e.cursor ? { cursor: e.cursor } : {}
+    }, x, { omitChainIds: !0, responseLimit: 256 * 1024 });
+    if (Date.parse(a.expiresAt) <= Date.now()) throw new h("snapshot-expired", 410);
+    const n = a.position, l = n.key;
+    if ((n.account !== r.query.account || n.chainId !== e.chainId || n.poolId !== e.poolId.toLowerCase() || n.kind !== e.kind || n.vaultId !== (e.vaultId ?? null) || n.scope !== (e.kind === "lend_shares" ? "account-lending" : "vault-lifetime") || a.page.snapshotId !== a.snapshotId || a.page.page !== ((o == null ? void 0 : o.page) ?? 0) || o && o.snapshotId !== a.snapshotId || a.page.page >= a.pageCount || a.recordCount > 0 && a.page.records.length === 0 || a.page.records.length > a.recordCount || a.pageCount === 1 && a.page.records.length !== a.recordCount || Date.parse(a.expiresAt) - Date.parse(a.createdAt) !== 6e5 || l.currency0 >= l.currency1 || k(y(
+      [{ type: "address" }, { type: "address" }, { type: "uint24" }, { type: "int24" }, { type: "address" }],
+      [l.currency0, l.currency1, l.fee, l.tickSpacing, l.hooks]
+    )) !== n.poolId) && c(), a.page.page + 1 < a.pageCount != (a.nextCursor !== null) && c(), a.nextCursor !== null)
+      try {
+        const t = v(a.nextCursor);
+        (t.snapshotId !== a.snapshotId || t.page !== a.page.page + 1) && c();
+      } catch {
+        c();
+      }
+    const m = /* @__PURE__ */ new Map();
+    let i;
+    for (const t of a.page.records) {
+      const s = t.event, p = m.get(s.transactionHash);
+      if ((s.blockNumber > a.frame.blockNumber || s.blockTimestamp > a.frame.blockTimestamp || i && (s.blockNumber < i.blockNumber || s.blockTimestamp < i.blockTimestamp || s.blockNumber === i.blockNumber && (s.logIndex <= i.logIndex || s.blockTimestamp !== i.blockTimestamp || s.transactionIndex < i.transactionIndex || s.transactionIndex === i.transactionIndex != (s.transactionHash === i.transactionHash))) || p && (p.blockNumber !== s.blockNumber || p.blockTimestamp !== s.blockTimestamp || p.transactionIndex !== s.transactionIndex)) && c(), t.type === "ownership")
+        (e.kind !== "borrow_vault" || t.event.vaultId !== e.vaultId || t.event.registry !== n.registry || s.id !== `vault-transfer:${n.chainId}:${n.registry}:${s.transactionHash}:${s.logIndex}` || s.blockNumber === a.frame.blockNumber && t.event.blockHash !== a.frame.blockHash) && c();
+      else {
+        const d = t.event, w = ["liquidity_modified", "share_transfer", "protocol_fee_minted"].includes(d.kind);
+        (e.kind === "lend_shares" !== w || d.kind === "liquidity_modified" && d.details.account !== n.account || d.kind === "protocol_fee_minted" && d.details.recipient !== n.account || d.kind === "share_transfer" && d.details.from !== n.account && d.details.to !== n.account) && c(), (t.event.id !== `engine-event:${n.chainId}:${n.engine}:${s.transactionHash}:${s.logIndex}` || t.event.sourceId !== `${s.transactionHash}-${s.logIndex}` || e.kind === "lend_shares" && t.ownershipAtEvent.status !== "not-applicable" || e.kind === "borrow_vault" && (a.ownership.status !== "complete" ? t.ownershipAtEvent.status !== "unavailable" : !["known", "inactive"].includes(t.ownershipAtEvent.status))) && c();
+      }
+      m.set(s.transactionHash, s), i = s;
+    }
+    return a;
+  });
+}
+const R = _({ ttlMs: 0, maxEntries: 64 });
+async function F(e) {
+  var n;
+  (n = e.signal) == null || n.throwIfAborted();
+  const r = { ...e.source, headers: { ...e.source.headers } }, o = JSON.stringify([
+    E(r.baseUrl),
+    S(r.headers),
+    r.timeoutMs,
+    e.account,
+    e.chainId,
+    e.poolId,
+    e.vaultId,
+    e.snapshotId
+  ]), a = R.read(o, () => $({ ...e, source: r, signal: void 0 }));
+  return structuredClone(await C(a, e.signal, "Position PnL read aborted."));
+}
+function $(e) {
+  return u({ ...e, chainIds: [e.chainId] }, async (r) => {
+    if (!/^0x[0-9a-fA-F]{64}$/.test(e.poolId) || !g.safeParse(e.vaultId).success || !I().uuid().safeParse(e.snapshotId).success) throw new h("invalid-query", 400);
+    const o = await f(r, "positions/pnl", {
+      chainId: String(e.chainId),
+      poolId: e.poolId.toLowerCase(),
+      kind: "borrow_vault",
+      vaultId: e.vaultId,
+      snapshotId: e.snapshotId
+    }, T, { omitChainIds: !0, responseLimit: 32 * 1024 });
+    if (Date.parse(o.expiresAt) <= Date.now()) throw new h("snapshot-expired", 410);
+    if ((o.account !== r.query.account || o.chainId !== e.chainId || o.poolId !== e.poolId.toLowerCase() || o.vaultId !== e.vaultId || o.snapshotId !== e.snapshotId || Date.parse(o.capturedAt) > Date.now() + 6e4 || Date.parse(o.expiresAt) - Date.parse(o.capturedAt) > 6e5) && c(), o.status === "token-pnl") {
+      const a = o.key;
+      k(y(
+        [{ type: "address" }, { type: "address" }, { type: "uint24" }, { type: "int24" }, { type: "address" }],
+        [a.currency0, a.currency1, a.fee, a.tickSpacing, a.hooks]
+      )) !== o.poolId && c();
+    }
+    return o;
+  });
+}
+function z(e) {
+  return u({ ...e, chainIds: [e.chainId] }, async (r) => {
+    if (!/^0x[0-9a-fA-F]{64}$/.test(e.poolId) || !g.safeParse(e.vaultId).success || !I().uuid().safeParse(e.snapshotId).success || e.portfolioSnapshotId !== void 0 && !I().uuid().safeParse(e.portfolioSnapshotId).success)
+      throw new h("invalid-query", 400);
+    const o = await f(r, "positions/performance", {
+      chainId: String(e.chainId),
+      poolId: e.poolId.toLowerCase(),
+      kind: "borrow_vault",
+      vaultId: e.vaultId,
+      snapshotId: e.snapshotId,
+      ...e.portfolioSnapshotId ? { portfolioSnapshotId: e.portfolioSnapshotId } : {}
+    }, D, { omitChainIds: !0, responseLimit: 32 * 1024 });
+    if (Date.parse(o.expiresAt) <= Date.now()) throw new h("snapshot-expired", 410);
+    return (o.account !== r.query.account || o.chainId !== e.chainId || o.poolId !== e.poolId.toLowerCase() || o.vaultId !== e.vaultId || o.snapshotId !== e.snapshotId || o.portfolioSnapshotId !== (e.portfolioSnapshotId ?? null) || Date.parse(o.capturedAt) > Date.now() + 6e4 || Date.parse(o.expiresAt) - Date.parse(o.capturedAt) > 6e5) && c(), o;
+  });
+}
+export {
+  h as AegisEngineAccountReadError,
+  M as createEngineTransactionHistory,
+  j as engineAccountPositionKey,
+  J as engineAccountTransactionKey,
+  O as engineHistoryCatalogResponseSchema,
+  U as enginePortfolioPriceFor,
+  G as enginePositionHistoryResponseSchema,
+  Z as engineTransactionStorageKey,
+  Q as fetchEngineAccountActivity,
+  V as fetchEngineAccountPortfolio,
+  W as fetchEngineHistoryPositions,
+  L as fetchEnginePositionAccounting,
+  X as fetchEnginePositionHistory,
+  z as fetchEnginePositionPerformance,
+  F as fetchEnginePositionPnl,
+  Y as fetchEngineTransactionStatus,
+  ee as formatEngineAccountTokenAmount,
+  ae as groupEngineAccountActivity,
+  oe as groupEnginePortfolioPositions,
+  se as mergeEngineTransactionRecord,
+  ne as parseEngineTransactionRecords,
+  te as resolveEngineAccountPositionTarget,
+  re as serializeEngineTransactionRecords
+};

package/dist/actions/allowance.d.ts

@@ -1,3 +1,14 @@
+import type { Hex } from 'viem';
+import type { AegisSwapApprovalMode } from '../swap/types.js';
+import type { AegisSwapToken } from '../config/index.js';
+import type { AegisSwapActionCallbacks, AegisSwapApprovalRequest } from './types.js';
+/**
+ * Whether replacing this token's non-zero allowance needs an approve(0)
+ * transaction first. The explicit token fact is the generic extension point;
+ * Ethereum USDT is recognized by address so a host cannot accidentally lose
+ * the well-known compatibility rule when it constructs its own token object.
+ */
+export declare function requiresErc20ApprovalReset(token: Pick<AegisSwapToken, 'chainId' | 'address' | 'requiresApprovalReset'>): boolean;
 /**
  * Polls an ERC-20 allowance read until it covers `minimum`, then asserts it did.
  * Shared by the direct-pool and KyberSwap approval flows after they submit an
@@ -5,3 +16,86 @@
  * the wallet approved a smaller amount, so the swap must not proceed.
  */
 export declare function confirmAllowanceReached(read: () => Promise<bigint>, minimum: bigint): Promise<bigint>;
+/**
+ * Sizes the ERC-20 grant a swap will request. Exported because a widget
+ * predicting the prompt before any executor exists calls the same function
+ * `ensureErc20Approval` writes from, so the predicted figure and the signed one
+ * cannot drift apart.
+ */
+export declare function erc20ApprovalRequest(amount: bigint, approvalMode: AegisSwapApprovalMode, decimals: number): AegisSwapApprovalRequest;
+export type Erc20AllowanceGrantStep = 'reset' | 'grant';
+export type Erc20AllowanceGrantResolution = {
+    requiredAllowance: bigint;
+    satisfied: boolean;
+    approvalRequired: boolean;
+    resetRequired: boolean;
+    planned: number;
+    /** Whether a review plan should render this grant at all. */
+    visible: boolean;
+};
+/**
+ * Resolves one ERC-20 allowance decision for both review planning and writes.
+ * Exact zero is a glance: it reports an existing grant but never invents a
+ * zero-value approval. Max mode always asks for effectively unlimited
+ * authority, even when a smaller standing allowance covers today's spend.
+ */
+export declare function resolveErc20AllowanceGrant(args: {
+    currentAllowance: bigint;
+    amount: bigint;
+    approvalMode: AegisSwapApprovalMode;
+    requiresReset?: boolean;
+    replaceAllowance?: boolean;
+}): Erc20AllowanceGrantResolution;
+type Erc20AllowanceWriteCallbacks = {
+    onWalletRequest?: () => void;
+    onHash?: (hash: Hex) => void;
+};
+/**
+ * Executes the decision above. Protocol-specific writers provide the spender;
+ * Engine can wrap each step with its lifecycle events and checkpoint without
+ * duplicating allowance sizing, reset ordering, or post-receipt proof.
+ */
+export declare function executeErc20AllowanceGrant(args: {
+    read: () => Promise<bigint>;
+    write: (step: Erc20AllowanceGrantStep, amount: bigint, callbacks?: Erc20AllowanceWriteCallbacks) => Promise<Hex>;
+    amount: bigint;
+    decimals: number;
+    approvalMode: AegisSwapApprovalMode;
+    requiresReset?: boolean;
+    replaceAllowance?: boolean;
+    knownAllowance?: bigint;
+    executeStep?: (step: Erc20AllowanceGrantStep, run: (callbacks?: Erc20AllowanceWriteCallbacks) => Promise<Hex>) => Promise<Hex>;
+    afterStep?: (step: Erc20AllowanceGrantStep, hash: Hex) => Promise<void>;
+    confirm?: typeof confirmAllowanceReached;
+    onStatus?: AegisSwapActionCallbacks['onStatus'];
+    onApprovalProgress?: AegisSwapActionCallbacks['onApprovalProgress'];
+}): Promise<{
+    approvalHashes: Hex[];
+    allowance: bigint;
+}>;
+/**
+ * Raises an ERC-20 allowance to what a swap needs: prompt plan, USDT-style
+ * zero-reset, the sized approval, and confirmation. The direct-pool and
+ * KyberSwap executors differ only in `write` — which spender they approve, and
+ * with which writer.
+ */
+export declare function ensureErc20Approval(args: {
+    read: () => Promise<bigint>;
+    /** Submits the approval for exactly `amount` and resolves once mined. */
+    write: (amount: bigint, callbacks?: Erc20AllowanceWriteCallbacks) => Promise<Hex>;
+    amount: bigint;
+    /** Decimals of the approved token, carried into the reported request. */
+    decimals: number;
+    approvalMode: AegisSwapApprovalMode;
+    /** Authoritative token compatibility fact; never infer this from allowance. */
+    requiresReset?: boolean;
+    replaceAllowance?: boolean;
+    /** Allowance the caller already read for this (token, owner, spender) tuple. */
+    knownAllowance?: bigint;
+    onStatus?: AegisSwapActionCallbacks['onStatus'];
+    onApprovalProgress?: AegisSwapActionCallbacks['onApprovalProgress'];
+}): Promise<{
+    approvalHashes: Hex[];
+    allowance: bigint;
+}>;
+export {};

package/dist/actions/directPoolSwap.d.ts

@@ -27,10 +27,17 @@ export declare function approveDirectPoolSwapInput(args: {
     wallet: WalletSession;
     publicClient: PublicClient;
     activeChain: AegisSwapChainConfig;
+    market: AegisSwapMarket;
     token: AegisSwapToken;
-    permit2: AegisSwapMarket['permit2'];
     amount: bigint;
     approvalMode?: AegisSwapApprovalMode;
+    /**
+     * ERC-20 -> Permit2 allowance the caller already read for this token and
+     * owner. executeDirectPoolSwap starts that read alongside its re-quote;
+     * passing it here saves a round trip right before the wallet prompt.
+     */
+    knownAllowance?: bigint;
+    signal?: AbortSignal;
     onStatus?: AegisSwapActionCallbacks['onStatus'];
     onApprovalProgress?: AegisSwapActionCallbacks['onApprovalProgress'];
 }): Promise<DirectPoolSwapApprovalResult>;
@@ -46,6 +53,8 @@ export declare function executeDirectPoolSwap(args: {
     slippageBps: number;
     displayedQuote?: DirectSwapQuote | null;
     approvalMode?: AegisSwapApprovalMode;
+    /** Finite cap for the next token and Permit2 approvals. Must cover the reviewed spend. */
+    approvalAmount?: bigint;
     signal?: AbortSignal;
     onWalletChainId?: (chainId: number | null) => void;
 } & AegisSwapActionCallbacks): Promise<AegisSwapActionResult<DirectSwapQuote>>;

package/dist/actions/kyberSwap.d.ts

@@ -22,7 +22,9 @@ export declare function approveKyberSwapInput(args: {
     spender: Address;
     amount: bigint;
     approvalMode?: AegisSwapApprovalMode;
+    signal?: AbortSignal;
     onStatus?: AegisSwapActionCallbacks['onStatus'];
+    onApprovalProgress?: AegisSwapActionCallbacks['onApprovalProgress'];
 }): Promise<KyberSwapApprovalResult>;
 export declare function executeKyberSwap(args: {
     wallet: WalletSession;

package/dist/actions/types.d.ts

@@ -1,3 +1,4 @@
+import type { AegisTransactionObservation } from '../swap/receiptWait.js';
 import type { Hex } from 'viem';
 import type { DirectSwapQuote } from '../quote.js';
 import type { AegisSwapReceiptSummary, SubmitStatus } from '../transactionProgress.js';
@@ -26,6 +27,8 @@ export type AegisSwapApprovalRequest = {
  * adds a second prompt, and only it sees that reset's receipt.
  */
 export type AegisSwapApprovalProgress = {
+    /** Broadcast approval awaiting its receipt; absent before signing and after settlement. */
+    pendingHash?: Hex;
     /** Prompts the approval step opens: 0, 1, or 2 when a zero-reset precedes it. */
     planned: number;
     /** How many of `planned` have landed on-chain. */
@@ -40,25 +43,29 @@ export type AegisSwapApprovalProgress = {
  * signatures fail closed, so this is a count rather than a boolean.
  */
 export type AegisSwapAuthorizationProgress = {
+    /** On-chain Permit2 fallback awaiting its receipt; signatures have no hash. */
+    pendingHash?: Hex;
     /** Prompts this authorization step will open from the executor's live state. */
     planned: number;
     /** Prompts already completed by the wallet/user. */
     completed: number;
 };
 export type AegisSwapActionCallbacks<TSwapDetails = AegisSwapSubmitDetails> = {
+    onTransactionObservation?: (event: AegisTransactionObservation) => void;
     onStatus?: (status: SubmitStatus) => void;
     onTxHash?: (hash: Hex | null) => void;
     onSubmitted?: (hash: Hex, swap?: TSwapDetails) => void;
     /**
-     * Fires with the plan before the first approval prompt opens, then again
-     * after each approval transaction mines. Once allowance resolution is
+     * Fires with the plan before the first approval prompt opens, when each
+     * approval is broadcast, and after it mines. Once allowance resolution is
      * reached, no required approval reports `{ planned: 0, completed: 0 }`.
      * Earlier chain-validation or quote failures can stop before this callback.
      */
     onApprovalProgress?: (progress: AegisSwapApprovalProgress) => void;
     /**
      * Fires before the first Permit2 authorization prompt, whenever the plan
-     * changes, and after each completed prompt. A reusable standing cap reports
+     * changes, when an on-chain fallback is broadcast, and after each completed
+     * prompt. A reusable standing cap reports
      * `{ planned: 0, completed: 0 }`.
      */
     onAuthorizationProgress?: (progress: AegisSwapAuthorizationProgress) => void;

package/dist/actions/wallet.d.ts

@@ -6,6 +6,7 @@ export declare function waitForProviderChain(provider: Eip1193Provider, targetCh
 export declare function ensureWalletChain(args: {
     provider: Eip1193Provider;
     chain: AegisSwapChainConfig;
+    signal?: AbortSignal;
     onChainId?: (chainId: number | null) => void;
 }): Promise<void>;
 export declare function resolveWalletSession(args?: {