@usesigil/kit 0.2.2 → 0.3.0

package/dist/dashboard/reads.js

@@ -3,9 +3,17 @@
  *
  * Each function is stateless (fetches fresh from RPC), composes existing
  * SDK functions, and returns raw values with toJSON() for MCP serialization.
+ *
+ * S14: the five view types are composed by pure `build*` helpers that take a
+ * shared {@link OverviewContext}. The existing reads each assemble their own
+ * context with minimal fetches; `getOverview` fetches once and shares the
+ * context across all helpers so derived values (security posture etc.) are
+ * computed exactly once.
  */
+import { isSome } from "@solana/kit";
+import { toDxError } from "./errors.js";
 import { resolveVaultStateForOwner, getSpendingHistory, getPendingPolicyForVault, } from "../state-resolver.js";
-import { getVaultPnL } from "../balance-tracker.js";
+import { getVaultPnL, getVaultPnLFromState } from "../balance-tracker.js";
 import { getSecurityPosture } from "../security-analytics.js";
 import { evaluateAlertConditions } from "../security-analytics.js";
 import { getAgentProfile } from "../agent-analytics.js";
@@ -40,15 +48,61 @@ function serializeBigints(obj) {
     }
     return obj;
 }
-// ─── getVaultState ───────────────────────────────────────────────────────────
-export async function getVaultState(rpc, vault, network) {
-    const [state, pnl] = await Promise.all([
-        resolveVaultStateForOwner(rpc, vault, undefined, toNet(network)),
-        getVaultPnL(rpc, vault, toNet(network)),
-    ]);
-    const posture = getSecurityPosture(asVaultState(state));
-    const v = state.vault;
-    const bal = state.stablecoinBalances;
+/**
+ * Default size of the activity window included in `getOverview`. Consumers
+ * may override via `GetOverviewOptions.activityLimit`.
+ *
+ * The value matches `getAgents`' existing per-agent enrichment window so one
+ * fetch serves both the overview's activity feed and the agents' last-action
+ * fields without inflating RPC cost.
+ */
+export const DEFAULT_OVERVIEW_ACTIVITY_LIMIT = 100;
+/**
+ * Shared "is this an account-not-found error?" predicate.
+ *
+ * Both `getPolicy` and `getOverview` treat a missing `PendingPolicyUpdate`
+ * account as "no pending update" (not an error). The current Kit doesn't
+ * expose a typed `AccountNotFound` SolanaError at this call site, so both
+ * paths fall back to substring matching. Extracting it here means the
+ * fragility lives in one place and only one site needs to update if Kit
+ * ever surfaces a typed variant.
+ */
+function isAccountNotFoundError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return (message.includes("could not find") ||
+        message.includes("Account does not exist"));
+}
+// ─── Build helpers (pure composition — no RPC) ───────────────────────────────
+// Each helper accepts an OverviewContext and returns one view type. `getOverview`
+// pre-populates memoized derivations (posture/breakdown/alerts) so repeat calls
+// share one computation; existing reads pass a minimal ctx and the helper
+// derives what it needs from `ctx.state`.
+/**
+ * Guard for state fields that `resolveVaultStateForOwner` normally guarantees.
+ *
+ * `state.vault` and `state.policy` are non-null on any success path from the
+ * resolver, but consumers that hand-construct an {@link OverviewContext} for
+ * testing or custom composition could pass a partial shape. Fail fast with a
+ * labeled error instead of a cryptic "cannot read properties of null".
+ */
+function requireCtxField(value, field) {
+    if (value === null || value === undefined) {
+        throw new Error(`[dashboard/reads] OverviewContext.state.${field} is required but missing`);
+    }
+    return value;
+}
+/**
+ * Compose {@link VaultState} from a pre-fetched {@link OverviewContext}.
+ *
+ * Requires `ctx.state`. Uses `ctx.pnl` when present; otherwise defaults to
+ * zero P&L. Uses `ctx.posture` when memoized; otherwise computes from state.
+ */
+export function buildVaultState(ctx) {
+    const v = requireCtxField(ctx.state.vault, "vault");
+    const posture = ctx.posture ?? getSecurityPosture(asVaultState(ctx.state));
+    const pnlPercent = ctx.pnl && Number.isFinite(ctx.pnl.pnlPercent) ? ctx.pnl.pnlPercent : 0;
+    const pnlAbsolute = ctx.pnl ? ctx.pnl.pnl : 0n;
+    const bal = ctx.state.stablecoinBalances;
     const total = bal.usdc + bal.usdt;
     const tokens = [
         ...(bal.usdc > 0n ? [{ mint: "USDC", amount: bal.usdc, decimals: 6 }] : []),
@@ -63,10 +117,12 @@ export async function getVaultState(rpc, vault, network) {
         : posture.failCount > 0
             ? "elevated"
             : "healthy";
+    const vaultAddr = ctx.vault;
+    const status = (v.status === 0 ? "active" : v.status === 1 ? "frozen" : "closed");
     return {
         vault: {
-            address: vault,
-            status: v.status === 0 ? "active" : v.status === 1 ? "frozen" : "closed",
+            address: vaultAddr,
+            status,
             owner: v.owner,
             agentCount: v.agents?.length ?? 0,
             openPositions: v.openPositions,
@@ -74,19 +130,12 @@ export async function getVaultState(rpc, vault, network) {
             totalFees: v.totalFeesCollected,
         },
         balance: { total, tokens },
-        pnl: {
-            percent: Number.isFinite(pnl.pnlPercent) ? pnl.pnlPercent : 0,
-            absolute: pnl.pnl,
-        },
+        pnl: { percent: pnlPercent, absolute: pnlAbsolute },
         health: { level, alertCount: posture.failCount, checks },
         toJSON: () => ({
             vault: {
-                address: vault,
-                status: (v.status === 0
-                    ? "active"
-                    : v.status === 1
-                        ? "frozen"
-                        : "closed"),
+                address: vaultAddr,
+                status,
                 owner: v.owner,
                 agentCount: v.agents?.length ?? 0,
                 openPositions: v.openPositions,
@@ -97,20 +146,25 @@ export async function getVaultState(rpc, vault, network) {
                 total: bs(total),
                 tokens: tokens.map((t) => ({ ...t, amount: bs(t.amount) })),
             },
-            pnl: {
-                percent: Number.isFinite(pnl.pnlPercent) ? pnl.pnlPercent : 0,
-                absolute: bs(pnl.pnl),
-            },
+            pnl: { percent: pnlPercent, absolute: bs(pnlAbsolute) },
             health: { level, alertCount: posture.failCount, checks },
         }),
     };
 }
-// ─── getAgents ───────────────────────────────────────────────────────────────
-export async function getAgents(rpc, vault, network) {
-    const state = await resolveVaultStateForOwner(rpc, vault, undefined, toNet(network));
-    const vaultAgents = state.vault.agents;
+/**
+ * Compose {@link AgentData}[] from a pre-fetched {@link OverviewContext}.
+ *
+ * Requires `ctx.state`. Uses `ctx.activity` to populate per-agent last-action
+ * and blocked-count fields; when absent, those fields default to empty/zero.
+ */
+export function buildAgents(ctx) {
+    const state = ctx.state;
+    const v = requireCtxField(state.vault, "vault");
+    const vaultAgents = v.agents;
     if (!vaultAgents || vaultAgents.length === 0)
         return [];
+    const activity = ctx.activity ?? [];
+    const blockedCutoffMs = Date.now() - 24 * 3600 * 1000;
     return vaultAgents.map((entry) => {
         const addr = entry.pubkey;
         const profile = getAgentProfile(asVaultState(state), addr);
@@ -118,39 +172,52 @@ export async function getAgents(rpc, vault, network) {
         const spentAmt = budget?.spent24h ?? 0n;
         const capAmt = budget?.cap ?? 0n;
         const pct = capAmt > 0n ? Number((spentAmt * 10000n) / capAmt) / 100 : 0;
+        // Items are newest-first (getSignaturesForAddress ordering).
+        const agentActivity = activity.filter((item) => item.agent !== null && item.agent === addr);
+        const last = agentActivity[0];
+        const lastActionType = last
+            ? mapCategory(last.category ?? "unknown", last.eventType ?? "", last.actionType ?? undefined)
+            : "";
+        const lastActionProtocol = last?.protocolName ?? "";
+        const lastActionTimestamp = last ? last.timestamp * 1000 : 0;
+        const blockedCount24h = agentActivity.filter((item) => !item.success && item.timestamp * 1000 >= blockedCutoffMs).length;
         return {
             address: addr,
             status: (profile?.paused ? "paused" : "active"),
-            permissions: profile?.permissionStrings ?? [],
-            permissionBitmask: profile?.permissions ?? 0n,
+            capabilityLabel: profile?.capabilityLabel ?? "Disabled",
+            capability: profile?.capability ?? 0,
             spending: { amount: spentAmt, limit: capAmt, percent: pct },
-            lastActionType: "",
-            lastActionProtocol: "",
-            lastActionTimestamp: 0,
-            blockedCount24h: 0,
+            lastActionType,
+            lastActionProtocol,
+            lastActionTimestamp,
+            blockedCount24h,
             toJSON: () => ({
                 address: addr,
                 status: profile?.paused ? "paused" : "active",
-                permissions: profile?.permissionStrings ?? [],
-                permissionBitmask: bs(profile?.permissions ?? 0n),
+                capabilityLabel: profile?.capabilityLabel ?? "Disabled",
+                capability: profile?.capability ?? 0,
                 spending: { amount: bs(spentAmt), limit: bs(capAmt), percent: pct },
-                lastActionType: "",
-                lastActionProtocol: "",
-                lastActionTimestamp: 0,
-                blockedCount24h: 0,
+                lastActionType,
+                lastActionProtocol,
+                lastActionTimestamp,
+                blockedCount24h,
             }),
         };
     });
 }
-// ─── getSpending ─────────────────────────────────────────────────────────────
-export async function getSpending(rpc, vault, network) {
-    const state = await resolveVaultStateForOwner(rpc, vault, undefined, toNet(network));
-    const breakdown = getSpendingBreakdown(asVaultState(state));
+/**
+ * Compose {@link SpendingData} from a pre-fetched {@link OverviewContext}.
+ *
+ * Requires `ctx.state`. Uses `ctx.breakdown` when memoized.
+ */
+export function buildSpending(ctx) {
+    const state = ctx.state;
+    const breakdown = ctx.breakdown ?? getSpendingBreakdown(asVaultState(state));
     const nowUnix = BigInt(Math.floor(Date.now() / 1000));
     const epochs = getSpendingHistory(state.tracker, nowUnix);
     const chart = epochs.map((e) => ({
         time: new Date(e.timestamp * 1000).toISOString(),
-        amount: Number(e.usdAmount),
+        amount: Number(e.usdAmount) / 1_000_000,
     }));
     const { spent24h: spent, cap, remaining } = state.globalBudget;
     const percent = cap > 0n ? Number((spent * 10000n) / cap) / 100 : 0;
@@ -184,109 +251,15 @@ export async function getSpending(rpc, vault, network) {
         }),
     };
 }
-// ─── getActivity ─────────────────────────────────────────────────────────────
-export async function getActivity(rpc, vault, network, filters) {
-    const limit = filters?.limit ?? 50;
-    const items = await getVaultActivity(rpc, vault, limit, toNet(network));
-    let rows = items.map((item, i) => {
-        const cat = item.category ?? "unknown";
-        const evt = item.eventType ?? "";
-        const act = item.actionType ?? undefined;
-        const type = mapCategory(cat, evt, act);
-        const amt = item.amount ?? 0n;
-        const sig = item.txSignature || `evt-${item.timestamp}-${item.eventType}`;
-        return {
-            id: sig,
-            timestamp: item.timestamp * 1000,
-            type,
-            protocol: item.protocolName || "",
-            protocolId: item.protocol || "",
-            agent: item.agent || "",
-            amount: amt,
-            status: item.success ? "approved" : "blocked",
-            reason: item.success ? undefined : item.description,
-            txSignature: item.txSignature,
-            toJSON: () => ({
-                id: sig,
-                timestamp: item.timestamp * 1000,
-                type,
-                protocol: item.protocolName || "",
-                protocolId: item.protocol || "",
-                agent: item.agent || "",
-                amount: bs(amt),
-                status: item.success ? "approved" : "blocked",
-                reason: item.success ? undefined : item.description,
-                txSignature: item.txSignature,
-            }),
-        };
-    });
-    if (filters?.agent)
-        rows = rows.filter((r) => r.agent === filters.agent);
-    if (filters?.protocol)
-        rows = rows.filter((r) => r.protocolId === filters.protocol || r.protocol === filters.protocol);
-    if (filters?.status)
-        rows = rows.filter((r) => r.status === filters.status);
-    if (filters?.timeRange) {
-        const cutoff = Date.now() - rangeToMs(filters.timeRange);
-        rows = rows.filter((r) => r.timestamp >= cutoff);
-    }
-    const approved = rows.filter((r) => r.status === "approved").length;
-    const blocked = rows.length - approved;
-    const volume = rows.reduce((s, r) => s + r.amount, 0n);
-    return {
-        rows,
-        summary: { total: rows.length, approved, blocked, volume },
-        toJSON: () => ({
-            rows: rows.map((r) => r.toJSON()),
-            summary: { total: rows.length, approved, blocked, volume: bs(volume) },
-        }),
-    };
-}
-function mapCategory(cat, evt, actionType) {
-    if (cat === "trade") {
-        // ActionAuthorized carries actionType to distinguish swap vs lend vs perps
-        if (actionType) {
-            const at = actionType.toLowerCase();
-            if (at.includes("lend") ||
-                at.includes("deposit") ||
-                at.includes("withdraw"))
-                return "lend";
-            if (at.includes("open") ||
-                at === "openposition" ||
-                at === "swapandopenposition")
-                return "open_position";
-            if (at.includes("close") || at === "closeposition")
-                return "close_position";
-        }
-        if (evt.includes("Open"))
-            return "open_position";
-        if (evt.includes("Close"))
-            return "close_position";
-        return "swap";
-    }
-    if (cat === "deposit")
-        return "deposit";
-    if (cat === "withdrawal")
-        return "withdraw";
-    if (evt === "AgentTransferExecuted")
-        return "transfer";
-    return "swap";
-}
-function rangeToMs(r) {
-    const map = {
-        "1h": 3600000,
-        "6h": 21600000,
-        "24h": 86400000,
-        "7d": 604800000,
-        "30d": 2592000000,
-    };
-    return map[r] ?? 86400000;
-}
-// ─── getHealth ───────────────────────────────────────────────────────────────
-export async function getHealth(rpc, vault, network) {
-    const state = await resolveVaultStateForOwner(rpc, vault, undefined, toNet(network));
-    const posture = getSecurityPosture(asVaultState(state));
-    const alerts = evaluateAlertConditions(state, vault);
+/**
+ * Compose {@link HealthData} from a pre-fetched {@link OverviewContext}.
+ *
+ * Requires `ctx.state` + `ctx.vault` (for alert evaluation). Uses `ctx.posture`
+ * and `ctx.alerts` when memoized.
+ */
+export function buildHealth(ctx) {
+    const posture = ctx.posture ?? getSecurityPosture(asVaultState(ctx.state));
+    const alerts = ctx.alerts ?? evaluateAlertConditions(ctx.state, ctx.vault);
     const level = posture.criticalFailures.length > 0
         ? "critical"
         : posture.failCount > 0
@@ -320,21 +293,16 @@ export async function getHealth(rpc, vault, network) {
         }),
     };
 }
-// ─── getPolicy ───────────────────────────────────────────────────────────────
-export async function getPolicy(rpc, vault, network) {
-    const [state, pendingPolicy] = await Promise.all([
-        resolveVaultStateForOwner(rpc, vault, undefined, toNet(network)),
-        getPendingPolicyForVault(rpc, vault).catch((err) => {
-            // Account-not-found is expected (no pending update) — return null.
-            // Re-throw RPC errors so they're not silently swallowed.
-            if (err?.message?.includes("could not find") ||
-                err?.message?.includes("Account does not exist")) {
-                return null;
-            }
-            throw err;
-        }),
-    ]);
-    const p = state.policy;
+/**
+ * Compose {@link PolicyData} from a pre-fetched {@link OverviewContext}.
+ *
+ * Requires `ctx.state`. Uses `ctx.pendingPolicy` (which may be `null` to mean
+ * "confirmed no pending update"); when `undefined` treats as no pending update.
+ */
+export function buildPolicy(ctx) {
+    const state = ctx.state;
+    const pendingPolicy = ctx.pendingPolicy ?? null;
+    const p = requireCtxField(state.policy, "policy");
     const protocols = (p.protocols || []);
     const approvedApps = protocols.map((addr) => ({
         name: resolveProtocolName(addr),
@@ -357,8 +325,40 @@ export async function getPolicy(rpc, vault, network) {
         const executesAtSec = Number(pp.executesAt ?? 0);
         const appliesAt = Number.isFinite(executesAtSec) ? executesAtSec * 1000 : 0;
         const nowSec = Math.floor(Date.now() / 1000);
+        // Decode each Option<T> field from PendingPolicyUpdate. Only Some fields
+        // land in `changes`. 14 fields total — every timelockable PolicyConfig field.
+        // Source: programs/sigil/src/state/pending_policy.rs
+        const changes = {};
+        if (isSome(pp.dailySpendingCapUsd))
+            changes.dailyCap = pp.dailySpendingCapUsd.value;
+        if (isSome(pp.maxTransactionAmountUsd))
+            changes.maxPerTrade = pp.maxTransactionAmountUsd.value;
+        if (isSome(pp.protocols))
+            changes.approvedApps = pp.protocols.value;
+        if (isSome(pp.protocolMode))
+            changes.protocolMode = modeMap[pp.protocolMode.value] || "unrestricted";
+        if (isSome(pp.hasProtocolCaps))
+            changes.hasProtocolCaps = pp.hasProtocolCaps.value;
+        if (isSome(pp.protocolCaps))
+            changes.protocolCaps = pp.protocolCaps.value;
+        if (isSome(pp.canOpenPositions))
+            changes.canOpenPositions = pp.canOpenPositions.value;
+        if (isSome(pp.maxConcurrentPositions))
+            changes.maxConcurrentPositions = pp.maxConcurrentPositions.value;
+        if (isSome(pp.maxSlippageBps))
+            changes.maxSlippageBps = pp.maxSlippageBps.value;
+        if (isSome(pp.maxLeverageBps))
+            changes.leverageLimit = pp.maxLeverageBps.value;
+        if (isSome(pp.allowedDestinations))
+            changes.allowedDestinations = pp.allowedDestinations.value;
+        if (isSome(pp.developerFeeRate))
+            changes.developerFeeRate = pp.developerFeeRate.value;
+        if (isSome(pp.sessionExpirySlots))
+            changes.sessionExpirySlots = pp.sessionExpirySlots.value;
+        if (isSome(pp.timelockDuration))
+            changes.timelock = Number(pp.timelockDuration.value);
         pendingUpdate = {
-            changes: {},
+            changes,
             appliesAt,
             canApply: executesAtSec > 0 && executesAtSec <= nowSec,
             canCancel: true,
@@ -408,4 +408,307 @@ export async function getPolicy(rpc, vault, network) {
         }),
     };
 }
+/**
+ * Map raw {@link VaultActivityItem}[] to {@link ActivityRow}[] with stable
+ * derived IDs and toJSON serializers. Pure — no filtering applied.
+ *
+ * Both `getActivity` (which then filters) and `getOverview` (which returns
+ * unfiltered) consume the output.
+ */
+export function buildActivityRows(items) {
+    return items.map((item) => {
+        const cat = item.category ?? "unknown";
+        const evt = item.eventType ?? "";
+        const act = item.actionType ?? undefined;
+        const posEffect = item.positionEffect ?? undefined;
+        const type = mapCategory(cat, evt, act, posEffect);
+        const amt = item.amount ?? 0n;
+        const sig = item.txSignature || `evt-${item.timestamp}-${item.eventType}`;
+        return {
+            id: sig,
+            timestamp: item.timestamp * 1000,
+            type,
+            protocol: item.protocolName || "",
+            protocolId: item.protocol || "",
+            agent: item.agent || "",
+            amount: amt,
+            status: item.success ? "approved" : "blocked",
+            reason: item.success ? undefined : item.description,
+            txSignature: item.txSignature,
+            toJSON: () => ({
+                id: sig,
+                timestamp: item.timestamp * 1000,
+                type,
+                protocol: item.protocolName || "",
+                protocolId: item.protocol || "",
+                agent: item.agent || "",
+                amount: bs(amt),
+                status: item.success ? "approved" : "blocked",
+                reason: item.success ? undefined : item.description,
+                txSignature: item.txSignature,
+            }),
+        };
+    });
+}
+// ─── getVaultState ───────────────────────────────────────────────────────────
+export async function getVaultState(rpc, vault, network) {
+    try {
+        const [state, pnl] = await Promise.all([
+            resolveVaultStateForOwner(rpc, vault, undefined, toNet(network)),
+            getVaultPnL(rpc, vault, toNet(network)),
+        ]);
+        return buildVaultState({ vault, state, pnl });
+    }
+    catch (err) {
+        throw toDxError(err, "OwnerClient.getVaultState");
+    }
+}
+// ─── getAgents ───────────────────────────────────────────────────────────────
+export async function getAgents(rpc, vault, network) {
+    try {
+        // Single getVaultActivity call is shared across all agents (N+1 prevention).
+        // Activity is enrichment, so a fetch failure degrades gracefully to empty
+        // last-action fields. Window: 100 most recent signatures — large enough to
+        // surface last action for low-volume agents without inflating RPC cost.
+        //
+        // Fix for docs/SECURITY-FINDINGS-2026-04-07.md Finding 5: the previous
+        // `.catch(() => [])` swallowed activity-fetch failures silently. If Helius
+        // started rate-limiting getSignaturesForAddress, every dashboard call would
+        // show "last action: never" for every agent forever and nobody would
+        // notice. Graceful degradation is still the right behavior (activity is
+        // enrichment, not core), but it must be observable — console.warn is the
+        // minimum bar.
+        const [state, activity] = await Promise.all([
+            resolveVaultStateForOwner(rpc, vault, undefined, toNet(network)),
+            getVaultActivity(rpc, vault, 100, toNet(network)).catch((err) => {
+                // eslint-disable-next-line no-console
+                console.warn("[OwnerClient.getAgents] activity enrichment failed — falling back to empty last-action fields:", err instanceof Error ? err.message : String(err));
+                return [];
+            }),
+        ]);
+        return buildAgents({ vault, state, activity });
+    }
+    catch (err) {
+        throw toDxError(err, "OwnerClient.getAgents");
+    }
+}
+// ─── getSpending ─────────────────────────────────────────────────────────────
+export async function getSpending(rpc, vault, network) {
+    try {
+        const state = await resolveVaultStateForOwner(rpc, vault, undefined, toNet(network));
+        return buildSpending({ vault, state });
+    }
+    catch (err) {
+        throw toDxError(err, "OwnerClient.getSpending");
+    }
+}
+// ─── getActivity ─────────────────────────────────────────────────────────────
+export async function getActivity(rpc, vault, network, filters) {
+    try {
+        const limit = filters?.limit ?? 50;
+        const items = await getVaultActivity(rpc, vault, limit, toNet(network));
+        let rows = buildActivityRows(items);
+        if (filters?.agent)
+            rows = rows.filter((r) => r.agent === filters.agent);
+        if (filters?.protocol)
+            rows = rows.filter((r) => r.protocolId === filters.protocol || r.protocol === filters.protocol);
+        if (filters?.status)
+            rows = rows.filter((r) => r.status === filters.status);
+        if (filters?.type)
+            rows = rows.filter((r) => r.type === filters.type);
+        if (filters?.timeRange) {
+            const cutoff = Date.now() - rangeToMs(filters.timeRange);
+            rows = rows.filter((r) => r.timestamp >= cutoff);
+        }
+        const approved = rows.filter((r) => r.status === "approved").length;
+        const blocked = rows.length - approved;
+        const volume = rows.reduce((s, r) => s + r.amount, 0n);
+        return {
+            rows,
+            summary: { total: rows.length, approved, blocked, volume },
+            toJSON: () => ({
+                rows: rows.map((r) => r.toJSON()),
+                summary: { total: rows.length, approved, blocked, volume: bs(volume) },
+            }),
+        };
+    }
+    catch (err) {
+        throw toDxError(err, "OwnerClient.getActivity");
+    }
+}
+function mapCategory(cat, evt, actionType, positionEffect) {
+    if (cat === "trade") {
+        // v6 events carry positionEffect ("increment"/"decrement"/"none") instead
+        // of actionType. Prefer it when present — actionType is null for post-
+        // ActionType-elimination events.
+        if (positionEffect === "increment")
+            return "open_position";
+        if (positionEffect === "decrement")
+            return "close_position";
+        // Legacy v5 event path: actionType carries swap vs lend vs perps detail.
+        if (actionType) {
+            const at = actionType.toLowerCase();
+            if (at.includes("lend") ||
+                at.includes("deposit") ||
+                at.includes("withdraw"))
+                return "lend";
+            if (at.includes("open") ||
+                at === "openposition" ||
+                at === "swapandopenposition")
+                return "open_position";
+            if (at.includes("close") || at === "closeposition")
+                return "close_position";
+        }
+        if (evt.includes("Open"))
+            return "open_position";
+        if (evt.includes("Close"))
+            return "close_position";
+        return "swap";
+    }
+    if (cat === "deposit")
+        return "deposit";
+    if (cat === "withdrawal")
+        return "withdraw";
+    if (evt === "AgentTransferExecuted")
+        return "transfer";
+    return "swap";
+}
+function rangeToMs(r) {
+    const map = {
+        "1h": 3600000,
+        "6h": 21600000,
+        "24h": 86400000,
+        "7d": 604800000,
+        "30d": 2592000000,
+    };
+    return map[r] ?? 86400000;
+}
+// ─── getHealth ───────────────────────────────────────────────────────────────
+export async function getHealth(rpc, vault, network) {
+    try {
+        const state = await resolveVaultStateForOwner(rpc, vault, undefined, toNet(network));
+        return buildHealth({ vault, state });
+    }
+    catch (err) {
+        throw toDxError(err, "OwnerClient.getHealth");
+    }
+}
+// ─── getPolicy ───────────────────────────────────────────────────────────────
+export async function getPolicy(rpc, vault, network) {
+    try {
+        const [state, pendingPolicy] = await Promise.all([
+            resolveVaultStateForOwner(rpc, vault, undefined, toNet(network)),
+            getPendingPolicyForVault(rpc, vault).catch((err) => {
+                // Account-not-found is expected (no pending update) — return null.
+                // Re-throw RPC errors so they're not silently swallowed.
+                if (isAccountNotFoundError(err))
+                    return null;
+                throw err;
+            }),
+        ]);
+        return buildPolicy({ vault, state, pendingPolicy });
+    }
+    catch (err) {
+        throw toDxError(err, "OwnerClient.getPolicy");
+    }
+}
+// ─── getOverview (S14) ───────────────────────────────────────────────────────
+/**
+ * Single-call overview bundle — resolves vault state once, composes all five
+ * view types (vault, agents, spending, health, policy) plus a raw activity
+ * list, with PnL derived from the resolved state (no duplicate resolve).
+ *
+ * **Actual RPC shape.** Calling the five individual reads duplicates the
+ * vault-state resolution up to five times. `getOverview` resolves state
+ * exactly once and computes PnL from it via {@link getVaultPnLFromState}.
+ * The activity fetch is independent: `getVaultActivity(limit)` issues one
+ * `getSignaturesForAddress` followed by up to `limit` sequential
+ * `getTransaction` calls, so the wall-time cost of the activity feed
+ * dominates regardless of this method. Net savings vs. five separate reads:
+ * state resolution count drops from ~5 → 1.
+ *
+ * Activity is **unfiltered**. For filtered activity, call {@link getActivity}
+ * with `ActivityFilters`.
+ *
+ * Graceful degradation: activity fetch failure degrades to empty activity
+ * (same observable pattern as `getAgents`, documented in
+ * `docs/SECURITY-FINDINGS-2026-04-07.md` Finding 5); pending-policy
+ * account-not-found is treated as "no pending update" (same as `getPolicy`).
+ * **PnL and state-resolution errors are NOT degraded** and propagate via
+ * `toDxError`. A pending-policy error that is NOT account-not-found (e.g.
+ * network failure) also propagates — it is NOT treated as "no pending
+ * update", even on the `includeActivity: false` lightweight path.
+ */
+export async function getOverview(rpc, vault, network, options) {
+    try {
+        const includeActivity = options?.includeActivity ?? true;
+        const activityLimit = options?.activityLimit ?? DEFAULT_OVERVIEW_ACTIVITY_LIMIT;
+        const net = toNet(network);
+        // Fan out every independent fetch in one Promise.all. State resolution,
+        // activity, and pending-policy have no cross-dependency, so wall time
+        // collapses to the slowest of the three. PnL is derived from state
+        // synchronously after — one state resolve, zero duplication.
+        const [state, activity, pendingPolicy] = await Promise.all([
+            resolveVaultStateForOwner(rpc, vault, undefined, net),
+            includeActivity
+                ? getVaultActivity(rpc, vault, activityLimit, net).catch((err) => {
+                    // Same graceful-degradation pattern as getAgents
+                    // (docs/SECURITY-FINDINGS-2026-04-07.md Finding 5): activity is
+                    // enrichment, not core, but the failure must be observable.
+                    // eslint-disable-next-line no-console
+                    console.warn("[OwnerClient.getOverview] activity fetch failed — falling back to empty:", err instanceof Error ? err.message : String(err));
+                    return [];
+                })
+                : Promise.resolve(undefined),
+            getPendingPolicyForVault(rpc, vault).catch((err) => {
+                if (isAccountNotFoundError(err))
+                    return null;
+                throw err;
+            }),
+        ]);
+        // PnL is pure from resolved state — no extra RPC.
+        const pnl = getVaultPnLFromState(state);
+        // Compute the three state-derived values exactly once and memoize on ctx.
+        // Every build* helper reads these via the `ctx.field ?? derive()` fallback
+        // so the memoized value short-circuits re-derivation.
+        const posture = getSecurityPosture(asVaultState(state));
+        const breakdown = getSpendingBreakdown(asVaultState(state));
+        const alerts = evaluateAlertConditions(state, vault);
+        const ctx = {
+            vault,
+            state,
+            pnl,
+            activity,
+            pendingPolicy,
+            posture,
+            breakdown,
+            alerts,
+        };
+        const vaultView = buildVaultState(ctx);
+        const agentsView = buildAgents(ctx);
+        const spendingView = buildSpending(ctx);
+        const healthView = buildHealth(ctx);
+        const policyView = buildPolicy(ctx);
+        const activityRows = buildActivityRows(activity ?? []);
+        return {
+            vault: vaultView,
+            agents: agentsView,
+            spending: spendingView,
+            health: healthView,
+            policy: policyView,
+            activity: activityRows,
+            toJSON: () => ({
+                vault: vaultView.toJSON(),
+                agents: agentsView.map((a) => a.toJSON()),
+                spending: spendingView.toJSON(),
+                health: healthView.toJSON(),
+                policy: policyView.toJSON(),
+                activity: activityRows.map((r) => r.toJSON()),
+            }),
+        };
+    }
+    catch (err) {
+        throw toDxError(err, "OwnerClient.getOverview");
+    }
+}
 //# sourceMappingURL=reads.js.map