@epicentral/sos-sdk 0.9.0-beta

package/short/preflight.ts

@@ -0,0 +1,619 @@
+import { toAddress } from "../client/program";
+import type { AddressLike, KitRpc } from "../client/types";
+import type { OptionType } from "../generated";
+import { fetchCollateralPool, fetchVault, fetchWriterPosition } from "../accounts/fetchers";
+import { fetchPoolLoansByMaker } from "../accounts/list";
+import { deriveAssociatedTokenAddress, deriveVaultPda, deriveWriterPositionPda } from "../accounts/pdas";
+import { resolveOptionAccounts } from "../accounts/resolve-option";
+import { invariant } from "../shared/errors";
+
+const TOKEN_ACCOUNT_AMOUNT_OFFSET = 64;
+const BPS_DENOMINATOR = 10_000n;
+/** Fixed-point scale for pool accumulators (matches on-chain `FP_SCALE = 10^12`). */
+const FP_SCALE = 1_000_000_000_000n;
+/** Mainnet-beta slots per year, matches `SLOTS_PER_YEAR` in option-program. */
+const SLOTS_PER_YEAR = 78_840_000n;
+
+
+function readTokenAccountAmount(data: Uint8Array): bigint {
+  if (data.length < TOKEN_ACCOUNT_AMOUNT_OFFSET + 8) return 0n;
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  return view.getBigUint64(TOKEN_ACCOUNT_AMOUNT_OFFSET, true);
+}
+
+async function fetchTokenAmount(rpc: KitRpc, tokenAccount: AddressLike): Promise<bigint> {
+  const response = await rpc.getAccountInfo(toAddress(tokenAccount), { encoding: "base64" }).send();
+  const info = response.value;
+  if (!info) return 0n;
+  const [base64Data] = info.data;
+  if (!base64Data) return 0n;
+  const decoded = atob(base64Data);
+  const bytes = new Uint8Array(decoded.length);
+  for (let i = 0; i < decoded.length; i++) bytes[i] = decoded.charCodeAt(i);
+  return readTokenAccountAmount(bytes);
+}
+
+function toBigInt(value: bigint | number): bigint {
+  return typeof value === "bigint" ? value : BigInt(value);
+}
+
+export function minBigInt(...values: bigint[]): bigint {
+  if (values.length === 0) return 0n;
+  return values.reduce((a, b) => (a < b ? a : b));
+}
+
+/**
+ * SPL balance can trail `proportionalCollateralShare` by a few base units
+ * (rounding / close-long debits vs `collateral_deposited`). Matches on-chain
+ * `collateral_vault_unwind_dust_epsilon` in option-program `pool.rs`.
+ */
+export function collateralVaultUnwindDustEpsilon(proportionalCollateralShare: bigint): bigint {
+  const fromPpm = (proportionalCollateralShare * 50n) / 1_000_000n;
+  const from10Bps = (proportionalCollateralShare * 10n) / 10_000n;
+  let a = fromPpm < 128_000n ? 128_000n : fromPpm;
+  const combined = a > from10Bps ? a : from10Bps;
+  return combined > 5_000_000n ? 5_000_000n : combined;
+}
+
+/**
+ * When the writer position reports no OMLP borrow state, do not treat unrelated
+ * active pool loan accounts (same maker+vault) as unwind repayment debt.
+ * Matches on-chain: repayment only runs when the writer still tracks active loans.
+ */
+export function writerPositionHasOngoingPoolLoanDebt(writerPosition: {
+  borrowedPrincipal: bigint | number;
+  activeLoanCount: number;
+}): boolean {
+  return toBigInt(writerPosition.borrowedPrincipal) !== 0n || writerPosition.activeLoanCount > 0;
+}
+
+/**
+ * Client-side mirror of `WriterPosition::claimable_theta` + `theta_balance()`.
+ * Computes the theta balance that will be available on-chain after the
+ * instruction calls `realize_theta(pool.acc_theta_per_oi_fp)`.
+ */
+function computeThetaBalance(
+  writerPosition: {
+    soldQty: bigint | number;
+    thetaEarned: bigint | number;
+    thetaClaimed: bigint | number;
+    lastPoolAccThetaFp: bigint | number;
+  },
+  poolAccThetaFp: bigint | number
+): bigint {
+  const accTheta = toBigInt(poolAccThetaFp);
+  const lastFp = toBigInt(writerPosition.lastPoolAccThetaFp);
+  const soldQty = toBigInt(writerPosition.soldQty);
+  const deltaFp = accTheta > lastFp ? accTheta - lastFp : 0n;
+  const pending = deltaFp > 0n && soldQty > 0n ? (soldQty * deltaFp) / FP_SCALE : 0n;
+  const earned = toBigInt(writerPosition.thetaEarned) + pending;
+  const claimed = toBigInt(writerPosition.thetaClaimed);
+  return earned > claimed ? earned - claimed : 0n;
+}
+
+/** `(value * numerator) / denominator`, saturating at 0 when denominator is 0. */
+function proportionalAmount(value: bigint, numerator: bigint, denominator: bigint): bigint {
+  if (denominator === 0n) return 0n;
+  return (value * numerator) / denominator;
+}
+
+export interface PreflightUnwindWriterUnsoldParams {
+  underlyingAsset: AddressLike;
+  optionType: OptionType;
+  strikePrice: number;
+  expirationDate: bigint | number;
+  writer: AddressLike;
+  unwindQty: bigint | number;
+  rpc: KitRpc;
+  programId?: AddressLike;
+  underlyingMint?: AddressLike;
+  /**
+   * @deprecated Wallet-based repayment is no longer supported under the
+   * theta-hedge model; unwind pays theta-first then proportional collateral,
+   * and reverts if the writer is insolvent (callers should route to the
+   * keeper rescue path instead).
+   */
+  writerRepaymentAccount?: AddressLike;
+}
+
+export interface UnwindLoanBreakdown {
+  loanAddress: string;
+  principal: bigint;
+  accruedInterest: bigint;
+  accruedProtocolFees: bigint;
+  newlyAccruedInterest: bigint;
+  newlyAccruedProtocolFees: bigint;
+  totalInterest: bigint;
+  totalProtocolFees: bigint;
+  totalOwed: bigint;
+}
+
+export interface UnwindPreflightSummary {
+  activeLoanCount: number;
+  totalPrincipal: bigint;
+  totalInterest: bigint;
+  totalProtocolFees: bigint;
+  totalOwed: bigint;
+  /** Proportional obligations for partial unwind (based on unwind ratio). */
+  proportionalPrincipal: bigint;
+  proportionalInterest: bigint;
+  proportionalProtocolFees: bigint;
+  proportionalTotalOwed: bigint;
+  /** Proportional collateral claim the writer is owed if all debt is paid. */
+  proportionalCollateralShare: bigint;
+  /** Collateral returned to the writer after debt (pre-leftover-theta). */
+  returnableCollateral: bigint;
+  /** Total funds on hand in the collateral vault (SPL balance). */
+  collateralVaultAvailable: bigint;
+  /**
+   * Realized + pending theta available to offset debt on unwind.
+   * Mirrors `writer_position.realize_theta` followed by `theta_balance()`.
+   */
+  thetaAvailable: bigint;
+  /**
+   * Portion of `thetaAvailable` used to repay the proportional debt.
+   * Zero when `premium_vault.mint != collateral_pool.collateral_mint`.
+   */
+  thetaToDebt: bigint;
+  /** Residual debt after theta, paid from `collateral_vault`. */
+  collateralToDebt: bigint;
+  /** True when theta can offset debt (mint match with collateral pool). */
+  premiumMintMatchesCollateralMint: boolean;
+  /**
+   * Shortfall against the writer's proportional collateral claim; non-zero
+   * means the writer is underwater and the keeper rescue path is required.
+   */
+  collateralClaimShortfall: bigint;
+  /**
+   * Shortfall between vault SPL balance and `proportionalCollateralShare` for
+   * this unwind slice, ignoring dust within `collateralVaultUnwindDustEpsilon`.
+   */
+  collateralVaultShortfall: bigint;
+  /** True when the writer cannot fully repay the requested slice. */
+  needsRescue: boolean;
+}
+
+export interface UnwindPreflightResult {
+  canUnwind: boolean;
+  canRepayRequestedSlice: boolean;
+  /** @deprecated Use {@link canRepayRequestedSlice}. */
+  canRepayFully: boolean;
+  reason?: string;
+  /** Requested unwind quantity (from client). */
+  requestedUnwindQty: bigint;
+  /**
+   * Quantity used for repayment math and `unwind_writer_unsold` — `min` of requested, on-chain
+   * unsold, pool escrow LONG balance, and writer SHORT balance (matches program checks).
+   */
+  effectiveUnwindQty: bigint;
+  writerPositionAddress: string;
+  /**
+   * @deprecated Under the theta-hedge model debt is repaid from theta +
+   * collateral vault; this field is retained for ABI compatibility and
+   * simply resolves to the writer's default underlying ATA.
+   */
+  writerRepaymentAccount: string;
+  collateralVaultAddress: string;
+  loans: Array<UnwindLoanBreakdown>;
+  summary: UnwindPreflightSummary;
+}
+
+function emptySummary(): UnwindPreflightSummary {
+  return {
+    activeLoanCount: 0,
+    totalPrincipal: 0n,
+    totalInterest: 0n,
+    totalProtocolFees: 0n,
+    totalOwed: 0n,
+    proportionalPrincipal: 0n,
+    proportionalInterest: 0n,
+    proportionalProtocolFees: 0n,
+    proportionalTotalOwed: 0n,
+    proportionalCollateralShare: 0n,
+    returnableCollateral: 0n,
+    collateralVaultAvailable: 0n,
+    thetaAvailable: 0n,
+    thetaToDebt: 0n,
+    collateralToDebt: 0n,
+    premiumMintMatchesCollateralMint: false,
+    collateralClaimShortfall: 0n,
+    collateralVaultShortfall: 0n,
+    needsRescue: false,
+  };
+}
+
+export async function preflightUnwindWriterUnsold(
+  params: PreflightUnwindWriterUnsoldParams
+): Promise<UnwindPreflightResult> {
+  const resolved = await resolveOptionAccounts({
+    underlyingAsset: params.underlyingAsset,
+    optionType: params.optionType,
+    strikePrice: params.strikePrice,
+    expirationDate: params.expirationDate,
+    programId: params.programId,
+    rpc: params.rpc,
+  });
+
+  invariant(
+    !!resolved.collateralVault && !!resolved.collateralPool && !!resolved.underlyingMint,
+    "Option/collateral pool state is required for unwind preflight."
+  );
+  invariant(
+    !!resolved.optionPoolData,
+    "Option pool state is required for unwind preflight (theta accumulator)."
+  );
+  invariant(
+    !!resolved.collateralPoolData,
+    "Collateral pool state is required for unwind preflight (collateral mint)."
+  );
+
+  const optionPoolData = resolved.optionPoolData;
+  const collateralPoolData = resolved.collateralPoolData;
+
+  const underlyingMint = params.underlyingMint ?? resolved.underlyingMint;
+  const [vaultPda] = await deriveVaultPda(underlyingMint, params.programId);
+  const vaultPdaAddress = toAddress(vaultPda);
+  const writerDefaultRepaymentAta = await deriveAssociatedTokenAddress(params.writer, underlyingMint);
+  // `writerRepaymentAccount` stays in the result for ABI compatibility with
+  // existing callers (e.g. wallet-fallback UX from pre-convergence), but it
+  // is not used on-chain anymore.
+  const writerRepaymentAddress = toAddress(
+    params.writerRepaymentAccount ?? writerDefaultRepaymentAta
+  );
+  const [writerPositionAddress] = await deriveWriterPositionPda(
+    resolved.optionPool,
+    params.writer,
+    params.programId
+  );
+
+  // #region agent log
+  const __debugIngest = (stage: string, data: Record<string, unknown>) => {
+    try {
+      fetch("http://127.0.0.1:7586/ingest/4a07cb33-954d-4b27-b1a3-08f1423b9d05", {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "X-Debug-Session-Id": "af65cf" },
+        body: JSON.stringify({
+          sessionId: "af65cf",
+          location: "sos-sdk/short/preflight.ts:preflightUnwindWriterUnsold",
+          message: stage,
+          data,
+          timestamp: Date.now(),
+          hypothesisId: "H2-i64-writerPosition-or-poolLoan-size",
+        }),
+      }).catch(() => {});
+    } catch {}
+  };
+  // #endregion
+  // #region agent log
+  __debugIngest("before_account_fetch", {
+    writerPositionAddress: String(writerPositionAddress),
+    collateralPool: String(resolved.collateralPool),
+    vaultPda: String(vaultPda),
+    writer: String(params.writer),
+  });
+  // #endregion
+
+  let writerPosition: Awaited<ReturnType<typeof fetchWriterPosition>> | null = null;
+  let collateralPool: Awaited<ReturnType<typeof fetchCollateralPool>> | null = null;
+  let vault: Awaited<ReturnType<typeof fetchVault>> | null = null;
+  let loans: Awaited<ReturnType<typeof fetchPoolLoansByMaker>> = [];
+  let currentSlot: bigint | number = 0n;
+  try {
+    writerPosition = await fetchWriterPosition(params.rpc, writerPositionAddress);
+    // #region agent log
+    __debugIngest("fetchWriterPosition_ok", { hasPosition: !!writerPosition });
+    // #endregion
+  } catch (e) {
+    // #region agent log
+    __debugIngest("fetchWriterPosition_throw", {
+      err: (e as Error)?.message ?? String(e),
+      stack: String((e as Error)?.stack ?? "").slice(0, 600),
+    });
+    // #endregion
+    throw e;
+  }
+  try {
+    collateralPool = await fetchCollateralPool(params.rpc, resolved.collateralPool);
+  } catch (e) {
+    // #region agent log
+    __debugIngest("fetchCollateralPool_throw", { err: (e as Error)?.message ?? String(e) });
+    // #endregion
+    throw e;
+  }
+  try {
+    vault = await fetchVault(params.rpc, vaultPda);
+  } catch (e) {
+    // #region agent log
+    __debugIngest("fetchVault_throw", { err: (e as Error)?.message ?? String(e) });
+    // #endregion
+    throw e;
+  }
+  try {
+    loans = await fetchPoolLoansByMaker(params.rpc, params.writer);
+    // #region agent log
+    __debugIngest("fetchPoolLoansByMaker_ok", { count: loans.length });
+    // #endregion
+  } catch (e) {
+    // #region agent log
+    __debugIngest("fetchPoolLoansByMaker_throw", {
+      err: (e as Error)?.message ?? String(e),
+      stack: String((e as Error)?.stack ?? "").slice(0, 600),
+    });
+    // #endregion
+    throw e;
+  }
+  currentSlot = await params.rpc.getSlot().send();
+
+  invariant(!!writerPosition, "Writer position is required for unwind preflight.");
+  invariant(!!collateralPool, "Collateral pool is required for unwind preflight.");
+  invariant(!!vault, "Vault state is required for unwind preflight.");
+  invariant(
+    !!resolved.escrowLongAccount && !!resolved.shortMint,
+    "Option pool escrow LONG and short mint are required for unwind preflight."
+  );
+
+  const writerShortAta = await deriveAssociatedTokenAddress(params.writer, resolved.shortMint);
+  const [escrowLongBal, writerShortBal] = await Promise.all([
+    fetchTokenAmount(params.rpc, resolved.escrowLongAccount),
+    fetchTokenAmount(params.rpc, writerShortAta),
+  ]);
+
+  const unwindQtyRequested = toBigInt(params.unwindQty);
+  const unsoldQty = toBigInt(writerPosition.unsoldQty);
+  const unwindQtyEffective = minBigInt(unwindQtyRequested, unsoldQty, escrowLongBal, writerShortBal);
+
+  const baseResult = (
+    canUnwind: boolean,
+    canRepayRequestedSlice: boolean,
+    reason: string | undefined,
+    effectiveQty: bigint
+  ): UnwindPreflightResult => ({
+    canUnwind,
+    canRepayRequestedSlice,
+    canRepayFully: canRepayRequestedSlice,
+    reason,
+    requestedUnwindQty: unwindQtyRequested,
+    effectiveUnwindQty: effectiveQty,
+    writerPositionAddress: String(writerPositionAddress),
+    writerRepaymentAccount: String(writerRepaymentAddress),
+    collateralVaultAddress: String(resolved.collateralVault),
+    loans: [],
+    summary: emptySummary(),
+  });
+
+  if (unwindQtyRequested <= 0n) {
+    return baseResult(false, false, "unwindQty must be > 0", 0n);
+  }
+  if (unwindQtyRequested > unsoldQty) {
+    return baseResult(false, false, "unwindQty exceeds writer unsold quantity", 0n);
+  }
+  if (unwindQtyEffective <= 0n) {
+    return baseResult(
+      false,
+      false,
+      "Pool escrow LONG balance or your SHORT token balance is insufficient for any unwind. Refresh positions or unwind a smaller amount.",
+      0n
+    );
+  }
+
+  const unwindQty = unwindQtyEffective;
+
+  const slotNow = toBigInt(currentSlot);
+  const protocolFeeBps = BigInt(vault.protocolFeeBps);
+  const loanBreakdown: Array<UnwindLoanBreakdown> = [];
+
+  const includePoolLoansForRepay = writerPositionHasOngoingPoolLoanDebt(writerPosition);
+
+  const vaultLoanCandidates = loans.filter(
+    (loan) => toAddress(loan.data.vault) === vaultPdaAddress && Number(loan.data.status) === 1
+  );
+
+  const writerPositionAddr = String(writerPositionAddress);
+  const matchingLoans = includePoolLoansForRepay
+    ? vaultLoanCandidates.filter(
+        (loan) => toAddress(loan.data.writerPosition) === writerPositionAddr
+      )
+    : [];
+
+  // The on-chain `sync_collateral_pool_debt` requires the writer-position-matching loans in
+  // `remaining_accounts` to be exactly `writer.active_loan_count`. Dev clusters can leave
+  // orphan PoolLoan PDAs with status==1 not tracked by the writer, so when matchingLoans >
+  // activeLoanCount we sort by nonce DESC and take the top-N (most recent borrows are the
+  // ones the writer accumulator tracks), then verify the principal sum matches
+  // writer.borrowed_principal as a safety check.
+  const sortByNonceDesc = (
+    a: (typeof matchingLoans)[number],
+    b: (typeof matchingLoans)[number]
+  ) => {
+    if (a.data.nonce > b.data.nonce) return -1;
+    if (a.data.nonce < b.data.nonce) return 1;
+    return String(a.address).localeCompare(String(b.address));
+  };
+  const positionLoans = includePoolLoansForRepay
+    ? matchingLoans.slice().sort(sortByNonceDesc).slice(0, writerPosition.activeLoanCount)
+    : [];
+
+  if (includePoolLoansForRepay) {
+    // #region agent log
+    __debugIngest("loan_selection", {
+      activeLoanCount: writerPosition.activeLoanCount,
+      matchingLoansFound: matchingLoans.length,
+      selectedCount: positionLoans.length,
+      selectedNonces: positionLoans.map((l) => Number(l.data.nonce)),
+      selectedPrincipalSum: positionLoans
+        .reduce((s, l) => s + toBigInt(l.data.principal), 0n)
+        .toString(),
+      writerBorrowedPrincipal: toBigInt(writerPosition.borrowedPrincipal).toString(),
+    });
+    // #endregion
+    if (positionLoans.length !== writerPosition.activeLoanCount) {
+      return baseResult(
+        false,
+        false,
+        `Pool loan set mismatch: writer tracks ${writerPosition.activeLoanCount} active loan(s) but only found ${matchingLoans.length} matching status==1 PoolLoan(s) for this writer position. Refresh positions.`,
+        unwindQtyEffective
+      );
+    }
+    const selectedPrincipalSum = positionLoans.reduce(
+      (sum, loan) => sum + toBigInt(loan.data.principal),
+      0n
+    );
+    const writerBorrowedPrincipal = toBigInt(writerPosition.borrowedPrincipal);
+    if (selectedPrincipalSum !== writerBorrowedPrincipal) {
+      return baseResult(
+        false,
+        false,
+        `Active pool loan principal mismatch: top-${writerPosition.activeLoanCount} loans by nonce sum to ${selectedPrincipalSum} but writer.borrowed_principal=${writerBorrowedPrincipal}. On-chain state is inconsistent (extra orphan PoolLoans for this writer). Use the keeper rescue path.`,
+        unwindQtyEffective
+      );
+    }
+  }
+
+  if (includePoolLoansForRepay) {
+    for (const loan of positionLoans) {
+      const principal = toBigInt(loan.data.principal);
+      const accruedInterest = toBigInt(loan.data.accruedInterest);
+      const accruedProtocolFees = toBigInt(loan.data.accruedProtocolFees);
+      const rateBps = BigInt(loan.data.rateBps);
+      const lastUpdateSlot = toBigInt(loan.data.lastUpdateSlot);
+      const slotsElapsed = slotNow > lastUpdateSlot ? slotNow - lastUpdateSlot : 0n;
+      const newlyAccruedInterest =
+        slotsElapsed > 0n ? (principal * rateBps * slotsElapsed) / BPS_DENOMINATOR / SLOTS_PER_YEAR : 0n;
+      const newlyAccruedProtocolFees =
+        slotsElapsed > 0n
+          ? (principal * protocolFeeBps * slotsElapsed) / BPS_DENOMINATOR / SLOTS_PER_YEAR
+          : 0n;
+      const totalInterest = accruedInterest + newlyAccruedInterest;
+      const totalProtocolFees = accruedProtocolFees + newlyAccruedProtocolFees;
+      const totalOwed = principal + totalInterest + totalProtocolFees;
+
+      loanBreakdown.push({
+        loanAddress: String(loan.address),
+        principal,
+        accruedInterest,
+        accruedProtocolFees,
+        newlyAccruedInterest,
+        newlyAccruedProtocolFees,
+        totalInterest,
+        totalProtocolFees,
+        totalOwed,
+      });
+    }
+  }
+
+  const totals = loanBreakdown.reduce(
+    (acc, item) => ({
+      principal: acc.principal + item.principal,
+      interest: acc.interest + item.totalInterest,
+      fees: acc.fees + item.totalProtocolFees,
+      owed: acc.owed + item.totalOwed,
+    }),
+    { principal: 0n, interest: 0n, fees: 0n, owed: 0n }
+  );
+
+  const collateralVaultAvailable = await fetchTokenAmount(
+    params.rpc,
+    resolved.collateralVault!
+  );
+
+  const writtenQty = toBigInt(writerPosition.writtenQty);
+  const proportionalPrincipal = proportionalAmount(totals.principal, unwindQty, writtenQty);
+  const proportionalInterest = proportionalAmount(totals.interest, unwindQty, writtenQty);
+  const proportionalProtocolFees = proportionalAmount(totals.fees, unwindQty, writtenQty);
+  const proportionalTotalOwed =
+    proportionalPrincipal + proportionalInterest + proportionalProtocolFees;
+
+  const collateralDeposited = toBigInt(writerPosition.collateralDeposited);
+  const proportionalCollateralShare = proportionalAmount(
+    collateralDeposited,
+    unwindQty,
+    writtenQty
+  );
+
+  // Theta balance after realize_theta(pool.acc_theta_per_oi_fp).
+  const thetaAvailable = computeThetaBalance(writerPosition, optionPoolData.accThetaPerOiFp);
+
+  // Theta can only offset debt when premium_vault.mint == omlp_vault.mint.
+  // In OPX, premium_vault.mint == option_pool.underlying_mint (enforced via
+  // `buyer_payment_account.mint == option_pool.underlying_mint`), and the
+  // OMLP vault is derived for the collateral mint. They match when the
+  // collateral pool's collateral_mint equals the option pool's underlying_mint.
+  const premiumMintMatchesCollateralMint =
+    toAddress(optionPoolData.underlyingMint) === toAddress(collateralPoolData.collateralMint);
+
+  const thetaToDebt = premiumMintMatchesCollateralMint
+    ? minBigInt(thetaAvailable, proportionalTotalOwed)
+    : 0n;
+  const collateralToDebt = proportionalTotalOwed - thetaToDebt;
+
+  // Full-repay-or-revert: writer's proportional collateral share MUST cover
+  // the residual debt after theta. A non-zero `collateralClaimShortfall`
+  // means the writer is insolvent on this slice and the keeper rescue path
+  // is required.
+  const collateralClaimShortfall =
+    collateralToDebt > proportionalCollateralShare
+      ? collateralToDebt - proportionalCollateralShare
+      : 0n;
+  // On-chain, `collateral_vault` pays `collateralToDebt` then returns
+  // `proportionalCollateralShare - collateralToDebt` to the writer — total
+  // `proportionalCollateralShare`. Ignore gaps ≤ dust epsilon (see
+  // `collateralVaultUnwindDustEpsilon`).
+  const rawCollateralVaultShortfall =
+    proportionalCollateralShare > collateralVaultAvailable
+      ? proportionalCollateralShare - collateralVaultAvailable
+      : 0n;
+  const vaultDustEps = collateralVaultUnwindDustEpsilon(proportionalCollateralShare);
+  const collateralVaultShortfall =
+    rawCollateralVaultShortfall > vaultDustEps ? rawCollateralVaultShortfall : 0n;
+
+  const returnableCollateral =
+    proportionalCollateralShare > collateralToDebt
+      ? proportionalCollateralShare - collateralToDebt
+      : 0n;
+
+  const needsRescue = collateralClaimShortfall > 0n || collateralVaultShortfall > 0n;
+  const canRepayRequestedSlice = !needsRescue;
+
+  let reason: string | undefined;
+  if (collateralClaimShortfall > 0n) {
+    reason =
+      "Writer position is underwater: realized theta + proportional collateral cannot repay the debt slice. Call the keeper rescue path (liquidate_writer_position_rescue).";
+  } else if (collateralVaultShortfall > 0n) {
+    reason =
+      "Collateral vault is too drained to settle this slice. Refresh positions and retry, or call the keeper rescue path.";
+  }
+
+  return {
+    canUnwind: true,
+    canRepayRequestedSlice,
+    canRepayFully: canRepayRequestedSlice,
+    reason,
+    requestedUnwindQty: unwindQtyRequested,
+    effectiveUnwindQty: unwindQtyEffective,
+    writerPositionAddress: String(writerPositionAddress),
+    writerRepaymentAccount: String(writerRepaymentAddress),
+    collateralVaultAddress: String(resolved.collateralVault),
+    loans: loanBreakdown,
+    summary: {
+      activeLoanCount: loanBreakdown.length,
+      totalPrincipal: totals.principal,
+      totalInterest: totals.interest,
+      totalProtocolFees: totals.fees,
+      totalOwed: totals.owed,
+      proportionalPrincipal,
+      proportionalInterest,
+      proportionalProtocolFees,
+      proportionalTotalOwed,
+      proportionalCollateralShare,
+      returnableCollateral,
+      collateralVaultAvailable,
+      thetaAvailable,
+      thetaToDebt,
+      collateralToDebt,
+      premiumMintMatchesCollateralMint,
+      collateralClaimShortfall,
+      collateralVaultShortfall,
+      needsRescue,
+    },
+  };
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "module": "es2022",
+    "target": "es2020",
+    "moduleResolution": "node",
+    "strict": true,
+    "declaration": true,
+    "outDir": "dist",
+    "skipLibCheck": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["dist", "node_modules"]
+}