@usesigil/kit 0.15.0 → 0.16.0

package/dist/dashboard/post-assertion-validation.js

@@ -0,0 +1,191 @@
+// ─── Constants (pinned to Rust source) ────────────────────────────────────
+// These MUST match the Rust constants. If they drift, the validator will
+// pass inputs the program then rejects (or vice-versa), producing confusing
+// round-trip failures. Keep in sync with `programs/sigil/src/state/*.rs`.
+/** `programs/sigil/src/state/post_assertions.rs:7` */
+const MAX_POST_ASSERTION_ENTRIES = 4;
+/** `programs/sigil/src/state/constraints.rs:9` */
+const MAX_CONSTRAINT_VALUE_LEN = 32;
+/** Operator IDs (0..=6) — see `programs/sigil/src/state/constraints.rs ConstraintOperator`. */
+const MAX_OPERATOR_VALUE = 6;
+/** AssertionMode IDs (0..=3) — see `programs/sigil/src/state/post_assertions.rs AssertionMode`. */
+const MAX_ASSERTION_MODE_VALUE = 3;
+/** CrossFieldLte enable bit. Every other bit is reserved; validator rejects unknown flags. */
+const CROSS_FIELD_LTE_FLAG = 0x01;
+/** CrossField payloads are parsed as u64 on-chain; 8 is the max byte length. */
+const CROSS_FIELD_MAX_VALUE_LEN = 8;
+/** Delta modes (MaxDecrease=1, MaxIncrease=2, NoChange=3) also parse as u64. */
+const DELTA_MAX_VALUE_LEN = 8;
+/**
+ * Numeric `DxError.code` for every PostAssertion validation failure.
+ *
+ * All validation-class failures share this single numeric code — the more
+ * specific `validationCode` string discriminates. 7008 is the existing SDK
+ * "PRECHECK_FAILED" bucket (see `dashboard/errors.ts` SIGIL_ERROR_TO_NUMERIC),
+ * which is semantically correct: the client-side validator IS a pre-check
+ * for the on-chain validate_entries call.
+ */
+export const DX_CODE_POST_ASSERTION_VALIDATION = 7008;
+/**
+ * Thrown by {@link validatePostAssertionEntries} when an entry fails any
+ * check the on-chain program would enforce.
+ *
+ * Structurally compatible with `DxError` — exposes `code: number`,
+ * `message: string`, and `recovery: string[]` so FE can render the error
+ * without re-wrapping. Also carries the typed `validationCode` (the
+ * specific failure reason) and `entryIndex` (the zero-based index of the
+ * offending entry, or `null` for batch-level failures).
+ *
+ * Mutation wrappers re-throw this instance directly — they do NOT wrap
+ * via `toDxError`. Wrapping would collapse the typed fields into
+ * `DX_ERROR_CODE_UNMAPPED` (7999), breaking the file docblock's promise
+ * that the FE can branch on `validationCode`.
+ */
+export class PostAssertionValidationError extends Error {
+    code;
+    validationCode;
+    entryIndex;
+    recovery;
+    /**
+     * Always `false` — this error is thrown at CLIENT validation time,
+     * BEFORE any RPC round-trip. Present to satisfy the DxError structural
+     * contract (every DxError carries `onChainReverted`; see FE↔BE
+     * contract v2.2 C2). Pre-existing callers need no migration.
+     */
+    onChainReverted = false;
+    constructor(validationCode, entryIndex, message) {
+        super(message);
+        this.name = "PostAssertionValidationError";
+        this.code = DX_CODE_POST_ASSERTION_VALIDATION;
+        this.validationCode = validationCode;
+        this.entryIndex = entryIndex;
+        this.recovery = [
+            entryIndex !== null
+                ? `Fix PostAssertion entry at index ${entryIndex} (${validationCode}) and retry.`
+                : `Fix PostAssertion batch (${validationCode}) and retry.`,
+        ];
+        // Preserve prototype chain under ES5 target
+        Object.setPrototypeOf(this, PostAssertionValidationError.prototype);
+    }
+}
+/**
+ * Validate a batch of PostAssertionEntry values against the exact rules
+ * the on-chain program enforces.
+ *
+ * Throws on the FIRST failing check (same as the Rust `for entry in entries`
+ * loop). Use a try/catch to recover; the error's `validationCode` +
+ * `entryIndex` identify the offending entry.
+ *
+ * @param entries Batch to check. Must be 1..=4 entries.
+ * @throws {PostAssertionValidationError} with the specific failure code.
+ */
+export function validatePostAssertionEntries(entries) {
+    // Input-shape guard: TS doesn't enforce runtime shape, so an `any` caller
+    // can pass null/undefined/non-array without a compiler warning. Without
+    // this, `entries.length` would throw a cryptic TypeError that `toDxError`
+    // collapses to code 7999.
+    if (!Array.isArray(entries)) {
+        throw new PostAssertionValidationError("entries_not_an_array", null, `PostAssertion entries must be an array, got ${entries === null ? "null" : typeof entries}`);
+    }
+    // Batch-level: entry count must be 1..=MAX.
+    if (entries.length === 0 || entries.length > MAX_POST_ASSERTION_ENTRIES) {
+        throw new PostAssertionValidationError("entry_count_out_of_range", null, `PostAssertion entry count must be 1..=${MAX_POST_ASSERTION_ENTRIES}, got ${entries.length}`);
+    }
+    entries.forEach((entry, index) => {
+        // Per-slot null guard — forEach skips truly empty slots but an array
+        // literal `[null, validEntry]` yields `entry === null` at index 0.
+        if (entry == null) {
+            throw new PostAssertionValidationError("entries_contain_null", index, `PostAssertion[${index}]: entry is ${entry === null ? "null" : "undefined"}`);
+        }
+        validateSingleEntry(entry, index);
+    });
+}
+// ─── Internal ─────────────────────────────────────────────────────────────
+/**
+ * Guard that rejects non-integer, out-of-range, non-finite, or negative
+ * numeric field values at the validator layer — BEFORE Codama's u8/u16/u32
+ * encoders would either silently truncate (`8.5` → `8`) or throw a
+ * different error class (`-1` → SolanaError).
+ *
+ * Having a single typed rejection point means every invalid numeric input
+ * surfaces as `PostAssertionValidationError` with the field's specific
+ * `validationCode`, rather than a grab-bag of Codama runtime failures.
+ */
+function requireUintInRange(value, field, max, code, index) {
+    if (typeof value !== "number" ||
+        !Number.isInteger(value) ||
+        value < 0 ||
+        value > max) {
+        throw new PostAssertionValidationError(code, index, `PostAssertion[${index}]: ${field} must be an integer 0..=${max}, got ${JSON.stringify(value)} (${typeof value})`);
+    }
+}
+function validateSingleEntry(entry, index) {
+    // Strict numeric shape checks — integer, non-negative, fits the on-chain
+    // field width. Catch non-integer (e.g. 8.5) and negative (-1) inputs that
+    // one-sided `> MAX` comparisons would miss.
+    requireUintInRange(entry.offset, "offset", 0xffff, "offset_out_of_range", index);
+    requireUintInRange(entry.valueLen, "value_len", MAX_CONSTRAINT_VALUE_LEN, "value_len_out_of_range", index);
+    requireUintInRange(entry.operator, "operator", MAX_OPERATOR_VALUE, "operator_out_of_range", index);
+    requireUintInRange(entry.assertionMode, "assertion_mode", MAX_ASSERTION_MODE_VALUE, "assertion_mode_out_of_range", index);
+    requireUintInRange(entry.crossFieldOffsetB, "cross_field_offset_b", 0xffff, "cross_field_offset_b_out_of_range", index);
+    requireUintInRange(entry.crossFieldMultiplierBps, "cross_field_multiplier_bps", 0xffffffff, "cross_field_multiplier_bps_out_of_range", index);
+    requireUintInRange(entry.crossFieldFlags, "cross_field_flags", 0xff, "cross_field_flags_out_of_range", index);
+    // value_len must additionally be >= 1 (the shared range check allows 0;
+    // on-chain requires > 0 because a zero-length value is a semantic no-op).
+    if (entry.valueLen === 0) {
+        throw new PostAssertionValidationError("value_len_out_of_range", index, `PostAssertion[${index}]: value_len must be 1..=${MAX_CONSTRAINT_VALUE_LEN}, got 0`);
+    }
+    // expected_value must be at least `value_len` bytes. Callers that pass
+    // a shorter buffer would have the on-chain program reject the entry —
+    // catch here instead.
+    if (entry.expectedValue.length < entry.valueLen) {
+        throw new PostAssertionValidationError("expected_value_too_short", index, `PostAssertion[${index}]: expected_value has ${entry.expectedValue.length} bytes but value_len=${entry.valueLen} (must be >= value_len)`);
+    }
+    // Delta modes (1/2/3) compare the pre/post snapshot as u64 — so the
+    // expected-value payload must fit in 8 bytes. The on-chain program
+    // enforces this; we mirror the check here.
+    if (entry.assertionMode >= 1 && entry.assertionMode <= 3) {
+        if (entry.valueLen > DELTA_MAX_VALUE_LEN) {
+            throw new PostAssertionValidationError("delta_mode_value_len_too_large", index, `PostAssertion[${index}]: delta assertion_mode=${entry.assertionMode} requires value_len <= ${DELTA_MAX_VALUE_LEN}, got ${entry.valueLen}`);
+        }
+    }
+    // CrossFieldLte enable bit. Since we already asserted integrality of
+    // crossFieldFlags above, the bitwise AND here is safe — no silent Int32
+    // truncation of a fractional input.
+    const crossFieldEnabled = (entry.crossFieldFlags & CROSS_FIELD_LTE_FLAG) !== 0;
+    if (crossFieldEnabled) {
+        // CrossFieldLte parses both field_A and field_B as u64 via le_bytes[0..8].
+        // Payload must fit. Upstream attacker path: value_len=16 with a crafted
+        // field would bypass the ratio check by silently truncating.
+        if (entry.valueLen > CROSS_FIELD_MAX_VALUE_LEN) {
+            throw new PostAssertionValidationError("cross_field_value_len_too_large", index, `PostAssertion[${index}]: CrossFieldLte requires value_len <= ${CROSS_FIELD_MAX_VALUE_LEN}, got ${entry.valueLen}`);
+        }
+        // CrossFieldLte is a ratio check and only composes with Absolute mode.
+        // Combining it with delta modes would read the snapshot as field_A,
+        // which is semantically nonsensical — the on-chain program hard-rejects.
+        if (entry.assertionMode !== 0) {
+            throw new PostAssertionValidationError("cross_field_requires_absolute_mode", index, `PostAssertion[${index}]: CrossFieldLte requires assertion_mode=0 (Absolute), got ${entry.assertionMode}`);
+        }
+        // multiplier_bps > 0. A zero multiplier collapses the ratio check to
+        // `field_A * 10000 <= 0 * field_B` (always false unless field_A == 0),
+        // which is either a no-op or a trap. Reject at authoring time.
+        if (entry.crossFieldMultiplierBps === 0) {
+            throw new PostAssertionValidationError("cross_field_multiplier_must_be_positive", index, `PostAssertion[${index}]: CrossFieldLte multiplier_bps must be > 0`);
+        }
+        // Only bit 0 is defined. Any other bit set indicates future-flag drift
+        // or misuse; the on-chain program rejects via `flags & 0xFE == 0`.
+        if ((entry.crossFieldFlags & 0xfe) !== 0) {
+            throw new PostAssertionValidationError("cross_field_unknown_flags", index, `PostAssertion[${index}]: cross_field_flags has reserved bits set: 0x${entry.crossFieldFlags.toString(16).padStart(2, "0")} (only bit 0 is defined)`);
+        }
+    }
+    else {
+        // CrossFieldLte disabled → both auxiliary fields MUST be zero.
+        // A nonzero value here is a callsite bug (forgot to clear fields after
+        // switching from CrossFieldLte to plain assertion) and the program
+        // rejects via matching check.
+        if (entry.crossFieldOffsetB !== 0 || entry.crossFieldMultiplierBps !== 0) {
+            throw new PostAssertionValidationError("cross_field_disabled_fields_must_be_zero", index, `PostAssertion[${index}]: CrossFieldLte disabled but cross_field_offset_b=${entry.crossFieldOffsetB}, cross_field_multiplier_bps=${entry.crossFieldMultiplierBps} (both must be 0)`);
+        }
+    }
+}
+//# sourceMappingURL=post-assertion-validation.js.map

package/dist/dashboard/post-assertion-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-assertion-validation.js","sourceRoot":"","sources":["../../src/dashboard/post-assertion-validation.ts"],"names":[],"mappings":"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"}

package/dist/dashboard/reads.d.ts

@@ -11,8 +11,9 @@
  * computed exactly once.
  */
 import type { Address, Rpc, SolanaRpcApi } from "../kit-adapter.js";
+import type { Alert } from "../security-analytics.js";
 import type { VaultActivityItem } from "../event-analytics.js";
-import type { VaultState, AgentData, SpendingData, ActivityData, ActivityFilters, ActivityRow, HealthData, PolicyData, OverviewContext, OverviewData, GetOverviewOptions } from "./types.js";
+import type { VaultState, AgentData, SpendingData, ActivityData, ActivityFilters, ActivityRow, HealthData, PolicyData, OverviewContext, OverviewData, GetOverviewOptions, RiskMetrics, AuditTrailEntry, AuditTrailOptions } from "./types.js";
 /**
  * Default size of the activity window included in `getOverview`. Consumers
  * may override via `GetOverviewOptions.activityLimit`.
@@ -135,4 +136,95 @@ export declare function getPolicy(rpc: Rpc<SolanaRpcApi>, vault: Address, networ
  * update", even on the `includeActivity: false` lightweight path.
  */
 export declare function getOverview(rpc: Rpc<SolanaRpcApi>, vault: Address, network: "devnet" | "mainnet", options?: GetOverviewOptions): Promise<OverviewData>;
+/**
+ * Compose a single {@link AgentData} from a pre-fetched {@link OverviewContext}.
+ *
+ * Reuses {@link buildAgents} and filters to the requested address. Returns
+ * `null` when the agent is not registered in the vault — callers that want
+ * the throwing surface use `getAgentDetail` instead.
+ *
+ * Activity-derived fields (`lastActionType` / `lastActionProtocol` /
+ * `lastActionTimestamp` / `blockedCount24h`) follow the same defaulting rules
+ * as `buildAgents`: empty/zero when `ctx.activity` is undefined.
+ *
+ * @experimental Part of the `build*` composition surface (S10). Signature and
+ * JSON shape may shift before v1.0.
+ *
+ * @see OwnerClient.getAgentDetail — the stable single-call alternative.
+ */
+export declare function buildAgentDetail(ctx: OverviewContext, agent: Address): AgentData | null;
+/**
+ * Single-agent detail wrapper around {@link getAgentProfile} + activity
+ * enrichment. Resolves vault state, fetches the same 100-event activity
+ * window as `getAgents`, and returns the {@link AgentData} for the requested
+ * agent.
+ *
+ * Throws a typed {@link SigilSdkDomainError} (mapped through `toDxError` to
+ * `SIGIL_ERROR__SDK__INVALID_PARAMS`) when the agent is not registered in
+ * the vault. Same graceful-degradation pattern as `getAgents` for activity
+ * fetch failures: enrichment fields default to empty/zero rather than
+ * propagating the failure.
+ */
+export declare function getAgentDetail(rpc: Rpc<SolanaRpcApi>, vault: Address, agent: Address, network: "devnet" | "mainnet"): Promise<AgentData>;
+/**
+ * Map an {@link Alert}[] to the four-level UI risk badge. Critical wins over
+ * warning, warning wins over info; absence of any alerts is "low".
+ *
+ * Pure helper — exposed for direct testing. Most consumers use
+ * {@link getRiskMetrics}.
+ */
+export declare function deriveRiskLevel(alerts: readonly Alert[]): RiskMetrics["riskLevel"];
+/**
+ * Compute {@link RiskMetrics} from a pre-fetched {@link OverviewContext}.
+ *
+ * Combines:
+ * - {@link getSpendingVelocity}(state.tracker, now, state.globalBudget) →
+ *   `currentRate` becomes `spendingVelocity`; `isAccelerating` and
+ *   `timeToCapSeconds` flow through directly.
+ * - 24h cap projection → `capVelocity = currentRate * 24 / cap × 100`
+ *   (clamped at 0 when cap is 0n).
+ * - {@link evaluateAlertConditions}(state, vault) → `riskLevel` via
+ *   {@link deriveRiskLevel}. Uses `ctx.alerts` when memoized.
+ *
+ * @experimental Part of the `build*` composition surface (S11). Signature and
+ * JSON shape may shift before v1.0.
+ *
+ * @see OwnerClient.getRiskMetrics — the stable single-call alternative.
+ */
+export declare function buildRiskMetrics(ctx: OverviewContext): RiskMetrics;
+/**
+ * Risk-tilt summary for a vault — current spending velocity, daily-cap
+ * projection, and a four-level risk badge derived from the alert stream.
+ *
+ * One state resolution + one alert evaluation. Use this for the dashboard's
+ * "is something concerning right now?" indicator. For deeper inspection,
+ * pair with `getOverview` (which embeds the alert list) or the
+ * `evaluateAlertConditions` export.
+ */
+export declare function getRiskMetrics(rpc: Rpc<SolanaRpcApi>, vault: Address, network: "devnet" | "mainnet"): Promise<RiskMetrics>;
+/**
+ * Filter raw {@link VaultActivityItem}[] to the audit subset and map each to
+ * an {@link AuditTrailEntry}. Pure — no RPC, no time-based filtering.
+ *
+ * Used by both `getAuditTrail` (which then applies the optional `since`
+ * timestamp filter) and direct callers that already have an activity list.
+ *
+ * @experimental Part of the `build*` composition surface (S12).
+ */
+export declare function buildAuditTrail(items: readonly VaultActivityItem[]): AuditTrailEntry[];
+/**
+ * Governance + security audit trail — the policy/agent/security/escrow
+ * subset of the vault's activity stream.
+ *
+ * Use this for an admin-facing "what changed?" feed: policy queue/apply
+ * cycles, agent registrations, vault freeze/resume events, and escrow
+ * lifecycle. Trades and fund movements are excluded — they live in
+ * `getActivity()`.
+ *
+ * Activity fetch shape: one `getSignaturesForAddress` + up to `limit`
+ * sequential `getTransaction` calls (see {@link getVaultActivity}).
+ * Default limit is 100 — large enough to surface a few weeks of governance
+ * activity for a typical vault without inflating RPC cost.
+ */
+export declare function getAuditTrail(rpc: Rpc<SolanaRpcApi>, vault: Address, network: "devnet" | "mainnet", opts?: AuditTrailOptions): Promise<AuditTrailEntry[]>;
 //# sourceMappingURL=reads.d.ts.map

package/dist/dashboard/reads.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reads.d.ts","sourceRoot":"","sources":["../../src/dashboard/reads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAkBpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAgB/D,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,WAAW,EAEX,UAAU,EACV,UAAU,EAGV,eAAe,EACf,YAAY,EACZ,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAyBpB;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,MAAM,CAAC;AA6BnD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,eAAe,GAAG,UAAU,CA4DhE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,SAAS,EAAE,CA2D7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,eAAe,GAAG,YAAY,CA+ChE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,UAAU,CA+C5D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,UAAU,CA+G5D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,iBAAiB,EAAE,GAClC,WAAW,EAAE,CAkCf;AAID,wBAAsB,aAAa,CACjC,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,EACtB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,GAAG,SAAS,GAC5B,OAAO,CAAC,UAAU,CAAC,CAUrB;AAID,wBAAsB,SAAS,CAC7B,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,EACtB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,GAAG,SAAS,GAC5B,OAAO,CAAC,SAAS,EAAE,CAAC,CAiCtB;AAID,wBAAsB,WAAW,CAC/B,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,EACtB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,GAAG,SAAS,GAC5B,OAAO,CAAC,YAAY,CAAC,CAYvB;AAID,wBAAsB,WAAW,CAC/B,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,EACtB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,GAAG,SAAS,EAC7B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,YAAY,CAAC,CAkCvB;AA0CD,wBAAsB,SAAS,CAC7B,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,EACtB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,GAAG,SAAS,GAC5B,OAAO,CAAC,UAAU,CAAC,CAYrB;AAID,wBAAsB,SAAS,CAC7B,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,EACtB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,GAAG,SAAS,GAC5B,OAAO,CAAC,UAAU,CAAC,CAerB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,EACtB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,GAAG,SAAS,EAC7B,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,YAAY,CAAC,CAmFvB"}
+{"version":3,"file":"reads.d.ts","sourceRoot":"","sources":["../../src/dashboard/reads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAapE,OAAO,KAAK,EAAiB,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAMrE,OAAO,KAAK,EAAE,iBAAiB,EAAiB,MAAM,uBAAuB,CAAC;AAgB9E,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,WAAW,EAEX,UAAU,EACV,UAAU,EAGV,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,iBAAiB,EAElB,MAAM,YAAY,CAAC;AA4BpB;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,MAAM,CAAC;AA6BnD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,eAAe,GAAG,UAAU,CA4DhE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,SAAS,EAAE,CA2D7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,eAAe,GAAG,YAAY,CA+ChE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,UAAU,CA+C5D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,UAAU,CA2G5D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,iBAAiB,EAAE,GAClC,WAAW,EAAE,CAkCf;AAID,wBAAsB,aAAa,CACjC,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,EACtB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,GAAG,SAAS,GAC5B,OAAO,CAAC,UAAU,CAAC,CAUrB;AAID,wBAAsB,SAAS,CAC7B,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,EACtB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,GAAG,SAAS,GAC5B,OAAO,CAAC,SAAS,EAAE,CAAC,CAiCtB;AAID,wBAAsB,WAAW,CAC/B,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,EACtB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,GAAG,SAAS,GAC5B,OAAO,CAAC,YAAY,CAAC,CAYvB;AAID,wBAAsB,WAAW,CAC/B,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,EACtB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,GAAG,SAAS,EAC7B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,YAAY,CAAC,CAkCvB;AA0CD,wBAAsB,SAAS,CAC7B,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,EACtB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,GAAG,SAAS,GAC5B,OAAO,CAAC,UAAU,CAAC,CAYrB;AAID,wBAAsB,SAAS,CAC7B,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,EACtB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,GAAG,SAAS,GAC5B,OAAO,CAAC,UAAU,CAAC,CAerB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,EACtB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,GAAG,SAAS,EAC7B,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,YAAY,CAAC,CAmFvB;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,eAAe,EACpB,KAAK,EAAE,OAAO,GACb,SAAS,GAAG,IAAI,CAGlB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,EACtB,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,GAAG,SAAS,GAC5B,OAAO,CAAC,SAAS,CAAC,CA6BpB;AAID;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,KAAK,EAAE,GACvB,WAAW,CAAC,WAAW,CAAC,CAW1B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,eAAe,GAAG,WAAW,CAwClE;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,EACtB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,GAAG,SAAS,GAC5B,OAAO,CAAC,WAAW,CAAC,CAYtB;AAmBD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,iBAAiB,EAAE,GAClC,eAAe,EAAE,CA4BnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,EACtB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,GAAG,SAAS,EAC7B,IAAI,CAAC,EAAE,iBAAiB,GACvB,OAAO,CAAC,eAAe,EAAE,CAAC,CAa5B"}

package/dist/dashboard/reads.js

@@ -21,6 +21,7 @@ import { getSecurityPosture } from "../security-analytics.js";
 import { evaluateAlertConditions } from "../security-analytics.js";
 import { getAgentProfile } from "../agent-analytics.js";
 import { getSpendingBreakdown } from "../spending-analytics.js";
+import { getSpendingVelocity } from "../spending-analytics.js";
 import { getVaultActivity } from "../event-analytics.js";
 import { resolveProtocolName } from "../protocol-names.js";
 /**
@@ -30,6 +31,8 @@ import { resolveProtocolName } from "../protocol-names.js";
 function asVaultState(state) {
     return state;
 }
+import { SigilSdkDomainError } from "../errors/sdk.js";
+import { SIGIL_ERROR__SDK__INVALID_PARAMS } from "../errors/codes.js";
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 function toNet(network) {
     return network === "mainnet" ? "mainnet-beta" : "devnet";
@@ -343,7 +346,7 @@ export function buildPolicy(ctx) {
     const dailyCap = p.dailySpendingCapUsd;
     const maxPerTrade = p.maxTransactionSizeUsd ?? 0n;
     const protocolCaps = (p.protocolCaps || []);
-    const sessionExpiry = p.sessionExpirySlots;
+    const sessionExpiry = p.sessionExpirySeconds;
     const policyVer = (p.policyVersion ?? 0n);
     const timelockSec = Number(p.timelockDuration);
     let pendingUpdate;
@@ -372,14 +375,12 @@ export function buildPolicy(ctx) {
             changes.protocolCaps = pp.protocolCaps.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.sessionExpirySeconds))
+            changes.sessionExpirySeconds = pp.sessionExpirySeconds.value;
         if (isSome(pp.timelockDuration))
             changes.timelock = Number(pp.timelockDuration.value);
         pendingUpdate = {
@@ -397,10 +398,9 @@ export function buildPolicy(ctx) {
         hasProtocolCaps: p.hasProtocolCaps,
         protocolCaps,
         maxSlippageBps: p.maxSlippageBps,
-        leverageLimitBps: p.maxLeverageBps,
         allowedDestinations: (p.allowedDestinations || []),
         developerFeeRate: p.developerFeeRate,
-        sessionExpirySlots: sessionExpiry,
+        sessionExpirySeconds: sessionExpiry,
         timelockSeconds: timelockSec,
         policyVersion: policyVer,
         pendingUpdate,
@@ -412,10 +412,9 @@ export function buildPolicy(ctx) {
             hasProtocolCaps: p.hasProtocolCaps,
             protocolCaps: protocolCaps.map(bs),
             maxSlippageBps: p.maxSlippageBps,
-            leverageLimitBps: p.maxLeverageBps,
             allowedDestinations: (p.allowedDestinations || []),
             developerFeeRate: p.developerFeeRate,
-            sessionExpirySlots: bs(sessionExpiry),
+            sessionExpirySeconds: bs(sessionExpiry),
             timelockSeconds: timelockSec,
             policyVersion: bs(policyVer),
             pendingUpdate: pendingUpdate
@@ -727,4 +726,234 @@ export async function getOverview(rpc, vault, network, options) {
         throw toDxError(err, "OwnerClient.getOverview");
     }
 }
+// ─── getAgentDetail (S10) ────────────────────────────────────────────────────
+/**
+ * Compose a single {@link AgentData} from a pre-fetched {@link OverviewContext}.
+ *
+ * Reuses {@link buildAgents} and filters to the requested address. Returns
+ * `null` when the agent is not registered in the vault — callers that want
+ * the throwing surface use `getAgentDetail` instead.
+ *
+ * Activity-derived fields (`lastActionType` / `lastActionProtocol` /
+ * `lastActionTimestamp` / `blockedCount24h`) follow the same defaulting rules
+ * as `buildAgents`: empty/zero when `ctx.activity` is undefined.
+ *
+ * @experimental Part of the `build*` composition surface (S10). Signature and
+ * JSON shape may shift before v1.0.
+ *
+ * @see OwnerClient.getAgentDetail — the stable single-call alternative.
+ */
+export function buildAgentDetail(ctx, agent) {
+    const all = buildAgents(ctx);
+    return all.find((a) => a.address === agent) ?? null;
+}
+/**
+ * Single-agent detail wrapper around {@link getAgentProfile} + activity
+ * enrichment. Resolves vault state, fetches the same 100-event activity
+ * window as `getAgents`, and returns the {@link AgentData} for the requested
+ * agent.
+ *
+ * Throws a typed {@link SigilSdkDomainError} (mapped through `toDxError` to
+ * `SIGIL_ERROR__SDK__INVALID_PARAMS`) when the agent is not registered in
+ * the vault. Same graceful-degradation pattern as `getAgents` for activity
+ * fetch failures: enrichment fields default to empty/zero rather than
+ * propagating the failure.
+ */
+export async function getAgentDetail(rpc, vault, agent, network) {
+    try {
+        const [state, activity] = await Promise.all([
+            resolveVaultStateForOwner(rpc, vault, undefined, toNet(network)),
+            getVaultActivity(rpc, vault, 100, toNet(network)).catch((err) => {
+                // Same redaction discipline as getAgents (PR 1.B).
+                const cause = redactCause(err);
+                getSigilModuleLogger().warn("[OwnerClient.getAgentDetail] activity enrichment failed — falling back to empty last-action fields", { cause: cause.message ?? cause.name ?? cause.code ?? "unknown" });
+                return [];
+            }),
+        ]);
+        const detail = buildAgentDetail({ vault, state, activity }, agent);
+        if (!detail) {
+            throw new SigilSdkDomainError(SIGIL_ERROR__SDK__INVALID_PARAMS, `Agent ${agent} is not registered in vault ${vault}`, { context: { field: "agent", received: agent } });
+        }
+        return detail;
+    }
+    catch (err) {
+        throw toDxError(err, "OwnerClient.getAgentDetail");
+    }
+}
+// ─── getRiskMetrics (S11) ────────────────────────────────────────────────────
+/**
+ * Map an {@link Alert}[] to the four-level UI risk badge. Critical wins over
+ * warning, warning wins over info; absence of any alerts is "low".
+ *
+ * Pure helper — exposed for direct testing. Most consumers use
+ * {@link getRiskMetrics}.
+ */
+export function deriveRiskLevel(alerts) {
+    let hasWarning = false;
+    let hasInfo = false;
+    for (const a of alerts) {
+        if (a.severity === "critical")
+            return "critical";
+        if (a.severity === "warning")
+            hasWarning = true;
+        else if (a.severity === "info")
+            hasInfo = true;
+    }
+    if (hasWarning)
+        return "high";
+    if (hasInfo)
+        return "elevated";
+    return "low";
+}
+/**
+ * Compute {@link RiskMetrics} from a pre-fetched {@link OverviewContext}.
+ *
+ * Combines:
+ * - {@link getSpendingVelocity}(state.tracker, now, state.globalBudget) →
+ *   `currentRate` becomes `spendingVelocity`; `isAccelerating` and
+ *   `timeToCapSeconds` flow through directly.
+ * - 24h cap projection → `capVelocity = currentRate * 24 / cap × 100`
+ *   (clamped at 0 when cap is 0n).
+ * - {@link evaluateAlertConditions}(state, vault) → `riskLevel` via
+ *   {@link deriveRiskLevel}. Uses `ctx.alerts` when memoized.
+ *
+ * @experimental Part of the `build*` composition surface (S11). Signature and
+ * JSON shape may shift before v1.0.
+ *
+ * @see OwnerClient.getRiskMetrics — the stable single-call alternative.
+ */
+export function buildRiskMetrics(ctx) {
+    const state = ctx.state;
+    const nowUnix = BigInt(Math.floor(Date.now() / 1000));
+    const velocity = getSpendingVelocity(state.tracker, nowUnix, state.globalBudget);
+    const alerts = ctx.alerts ?? evaluateAlertConditions(state, ctx.vault);
+    // capVelocity: percent of daily cap consumed in 24h at current rate.
+    // 0 when cap is unset (matches alert logic which only fires on cap > 0).
+    const cap = state.globalBudget.cap;
+    let capVelocity = 0;
+    if (cap > 0n && velocity.currentRate > 0n) {
+        // Promote to Number for the percent calc — rate × 24 / cap × 100.
+        // currentRate is hourly USD base units; cap is total USD base units.
+        capVelocity = (Number(velocity.currentRate * 24n) / Number(cap)) * 100;
+    }
+    const riskLevel = deriveRiskLevel(alerts);
+    const spendingVelocity = velocity.currentRate;
+    const isAccelerating = velocity.isAccelerating;
+    const timeToCapSeconds = velocity.timeToCapSeconds;
+    return {
+        capVelocity,
+        spendingVelocity,
+        riskLevel,
+        isAccelerating,
+        timeToCapSeconds,
+        toJSON: () => ({
+            capVelocity,
+            spendingVelocity: bs(spendingVelocity),
+            riskLevel,
+            isAccelerating,
+            timeToCapSeconds,
+        }),
+    };
+}
+/**
+ * Risk-tilt summary for a vault — current spending velocity, daily-cap
+ * projection, and a four-level risk badge derived from the alert stream.
+ *
+ * One state resolution + one alert evaluation. Use this for the dashboard's
+ * "is something concerning right now?" indicator. For deeper inspection,
+ * pair with `getOverview` (which embeds the alert list) or the
+ * `evaluateAlertConditions` export.
+ */
+export async function getRiskMetrics(rpc, vault, network) {
+    try {
+        const state = await resolveVaultStateForOwner(rpc, vault, undefined, toNet(network));
+        return buildRiskMetrics({ vault, state });
+    }
+    catch (err) {
+        throw toDxError(err, "OwnerClient.getRiskMetrics");
+    }
+}
+// ─── getAuditTrail (S12) ─────────────────────────────────────────────────────
+/**
+ * Categories from {@link getVaultActivity} that count as audit events.
+ *
+ * Trades, deposits, withdrawals, and fee accruals are routine operating
+ * activity and are excluded. Constraint changes ride alongside policy
+ * changes (the underlying decoder maps them all to `policy`), so they are
+ * captured under `policy_change`.
+ */
+const AUDIT_CATEGORY_TO_TYPE = {
+    policy: "policy_change",
+    agent: "agent_change",
+    security: "vault_security",
+    escrow: "escrow",
+};
+/**
+ * Filter raw {@link VaultActivityItem}[] to the audit subset and map each to
+ * an {@link AuditTrailEntry}. Pure — no RPC, no time-based filtering.
+ *
+ * Used by both `getAuditTrail` (which then applies the optional `since`
+ * timestamp filter) and direct callers that already have an activity list.
+ *
+ * @experimental Part of the `build*` composition surface (S12).
+ */
+export function buildAuditTrail(items) {
+    const out = [];
+    for (const item of items) {
+        const eventType = AUDIT_CATEGORY_TO_TYPE[item.category];
+        if (!eventType)
+            continue;
+        const timestamp = item.timestamp * 1000;
+        const eventName = item.eventType ?? "";
+        const actor = item.agent || "";
+        const details = item.description;
+        const txSignature = item.txSignature;
+        out.push({
+            timestamp,
+            eventType,
+            eventName,
+            actor,
+            details,
+            txSignature,
+            toJSON: () => ({
+                timestamp,
+                eventType,
+                eventName,
+                actor,
+                details,
+                txSignature,
+            }),
+        });
+    }
+    return out;
+}
+/**
+ * Governance + security audit trail — the policy/agent/security/escrow
+ * subset of the vault's activity stream.
+ *
+ * Use this for an admin-facing "what changed?" feed: policy queue/apply
+ * cycles, agent registrations, vault freeze/resume events, and escrow
+ * lifecycle. Trades and fund movements are excluded — they live in
+ * `getActivity()`.
+ *
+ * Activity fetch shape: one `getSignaturesForAddress` + up to `limit`
+ * sequential `getTransaction` calls (see {@link getVaultActivity}).
+ * Default limit is 100 — large enough to surface a few weeks of governance
+ * activity for a typical vault without inflating RPC cost.
+ */
+export async function getAuditTrail(rpc, vault, network, opts) {
+    try {
+        const limit = opts?.limit ?? 100;
+        const items = await getVaultActivity(rpc, vault, limit, toNet(network));
+        let entries = buildAuditTrail(items);
+        if (opts?.since !== undefined) {
+            const since = opts.since;
+            entries = entries.filter((e) => e.timestamp >= since);
+        }
+        return entries;
+    }
+    catch (err) {
+        throw toDxError(err, "OwnerClient.getAuditTrail");
+    }
+}
 //# sourceMappingURL=reads.js.map