Fix: Build the Historical Epoch Ledger and NAV Drift Observability

src/lib/api/vaults.ts

@@ -49,6 +49,9 @@ import { submitTransactionXdr } from "./stellar";
  *   GET /api/v1/vaults/positions
  *   → VaultPositionWire[]  (one row per vault the wallet holds; `error` set when that vault failed)
  *
+ *   GET /api/v1/vaults/{id}/epochs
+ *   → VaultEpochLedgerEntry[]   (append-only, derived from on-chain epoch events)
+ *
  *   POST /api/v1/vaults/disclosures/acknowledge
  *     { disclosure_version, text_hash, jurisdiction_attested }  → DisclosureAcknowledgement
  *   GET  /api/v1/vaults/disclosures/me  → DisclosureAcknowledgement[]
@@ -652,6 +655,27 @@ export interface EpochRecord {
   pnlPct: number; // epoch return, positive = profit for depositors
 }
 
+/** Schema version of VaultEpochLedgerEntry. Bump on any breaking field change. */
+export const VAULT_EPOCH_LEDGER_SCHEMA_VERSION = 1;
+
+/**
+ * One append-only epoch ledger row, derived from on-chain epoch events.
+ * Rows are never edited in place; a correction is a new reconciliation row.
+ */
+export interface VaultEpochLedgerEntry {
+  schemaVersion: typeof VAULT_EPOCH_LEDGER_SCHEMA_VERSION;
+  vaultId: string;
+  epochNumber: number;
+  strategy: VaultStrategy;
+  startedAt: string; // ISO — on-chain epoch start timestamp
+  endedAt: string | null; // ISO — null while the epoch is still open
+  premium: number; // USD, total premium collected in the epoch
+  realizedPnl: number; // USD
+  navBefore: number; // USD per share at epoch start
+  navAfter: number | null; // USD per share at epoch end; null while open
+  feeTaken: number; // USD, management + performance fees taken in the epoch
+}
+
 /** The user's position in a vault. */
 export interface UserVaultPosition {
   shares: number;
@@ -739,45 +763,4 @@ export interface ShadowState {
   navSeries: ShadowNavPoint[];
   /** Shadow epoch record stream (never merged into `historicalEpochs`). */
   epochs: EpochRecord[];
-  /** Side-by-side comparison data for the operator console/analytics. */
-  comparison: ShadowComparison;
-}
-
-/**
- * Promotion criteria that must be met before a shadow strategy can be
- * moved to live allocation. Evaluated by the backend promotion gate; the
- * adapter surfaces the thresholds so the operator console can display
- * progress and block promotion when unmet.
- */
-export interface PromotionCriteria {
-  /** Minimum number of complete shadow epochs required. */
-  minCompleteEpochs: number;
-  /** Max allowed |shadow − expected| NAV deviation per share (USD). */
-  maxNavDeviation: number;
-  /** Whether any invariant violations were recorded during the run. */
-  invariantViolations: number;
-}
-
-export interface QueueState {
-  depositPendingUsd: number;
-  withdrawPendingShares: number;
-  settlesAt: string; // ISO
-}
-
-export interface FeeAccrual {
-  managementAccruedUsd: number;
-  performanceAccruedUsd: number;
-  accruedThrough: string; // ISO
-}
-
-export interface NavPoint {
-  at: string; // ISO
-  sharePrice: number;
-  totalShares: number;
-}
-
-/** Full detail for a single vault. */
-export interface VaultDetail extends VaultSummary {
-  currentEpoch: number;
-  currentPhase: EpochPhase;
-  phaseEndsAt: string; // ISO — when the current phase
+  /** Side-by-side comparison data for the operator console/analytics