@usesigil/kit 0.13.0 → 0.16.0

package/dist/dashboard/post-assertion-validation.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @usesigil/kit/dashboard — Client-side PostAssertionEntry validator.
+ *
+ * Mirrors the on-chain `PostExecutionAssertions::validate_entries()` check
+ * in `programs/sigil/src/state/post_assertions.rs:118`. Fails fast in the
+ * dashboard before the caller burns an RPC round-trip on an entry the
+ * program will reject.
+ *
+ * Pure function: no RPC, no I/O, no side effects. Safe to call in a render
+ * loop or form handler.
+ *
+ * Every rejection path carries a human-readable message that includes the
+ * offending entry index so callers can pinpoint the bad entry in a multi-
+ * entry batch (Phase 2 PRD ISC-19).
+ *
+ * ## DxError compatibility
+ *
+ * {@link PostAssertionValidationError} is structurally a `DxError` — it has
+ * numeric `code`, string `message`, and `recovery: string[]`. This means
+ * the mutation wrapper does NOT need to wrap it via `toDxError` before
+ * re-throwing; FE always sees the typed fields (`validationCode`,
+ * `entryIndex`) intact alongside the standard DxError surface.
+ *
+ * @see programs/sigil/src/state/post_assertions.rs — source of truth
+ */
+import type { PostAssertionEntry } from "../generated/types/postAssertionEntry.js";
+/**
+ * Machine-readable validation failure codes.
+ *
+ * Callers can branch on these via `err.validationCode` to produce tier-
+ * appropriate UI messaging without string-matching the human `message`
+ * field. The enum ordering mirrors the on-chain check sequence so the
+ * first failure a caller sees is also the first one `validate_entries`
+ * would reject.
+ */
+export type PostAssertionValidationCode = "entries_not_an_array" | "entries_contain_null" | "entry_count_out_of_range" | "value_len_out_of_range" | "expected_value_too_short" | "operator_out_of_range" | "assertion_mode_out_of_range" | "offset_out_of_range" | "cross_field_offset_b_out_of_range" | "cross_field_multiplier_bps_out_of_range" | "cross_field_flags_out_of_range" | "delta_mode_value_len_too_large" | "cross_field_value_len_too_large" | "cross_field_requires_absolute_mode" | "cross_field_multiplier_must_be_positive" | "cross_field_unknown_flags" | "cross_field_disabled_fields_must_be_zero";
+/**
+ * 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 declare 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 declare class PostAssertionValidationError extends Error {
+    readonly code: number;
+    readonly validationCode: PostAssertionValidationCode;
+    readonly entryIndex: number | null;
+    readonly recovery: string[];
+    /**
+     * 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.
+     */
+    readonly onChainReverted: boolean;
+    constructor(validationCode: PostAssertionValidationCode, entryIndex: number | null, message: string);
+}
+/**
+ * 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 declare function validatePostAssertionEntries(entries: readonly PostAssertionEntry[]): void;
+//# sourceMappingURL=post-assertion-validation.d.ts.map

package/dist/dashboard/post-assertion-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-assertion-validation.d.ts","sourceRoot":"","sources":["../../src/dashboard/post-assertion-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0CAA0C,CAAC;AA0BnF;;;;;;;;GAQG;AACH,MAAM,MAAM,2BAA2B,GACnC,sBAAsB,GACtB,sBAAsB,GACtB,0BAA0B,GAC1B,wBAAwB,GACxB,0BAA0B,GAC1B,uBAAuB,GACvB,6BAA6B,GAC7B,qBAAqB,GACrB,mCAAmC,GACnC,yCAAyC,GACzC,gCAAgC,GAChC,gCAAgC,GAChC,iCAAiC,GACjC,oCAAoC,GACpC,yCAAyC,GACzC,2BAA2B,GAC3B,0CAA0C,CAAC;AAE/C;;;;;;;;GAQG;AACH,eAAO,MAAM,iCAAiC,EAAG,IAAa,CAAC;AAE/D;;;;;;;;;;;;;;GAcG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,cAAc,EAAE,2BAA2B,CAAC;IAC5D,SAAgB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,SAAgB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnC;;;;;OAKG;IACH,SAAgB,eAAe,EAAE,OAAO,CAAS;gBAG/C,cAAc,EAAE,2BAA2B,EAC3C,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,OAAO,EAAE,MAAM;CAelB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,SAAS,kBAAkB,EAAE,GACrC,IAAI,CAkCN"}

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,CA8DhE;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,CAuH5D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,iBAAiB,EAAE,GAClC,WAAW,EAAE,CAmCf;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;AAuDD,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":"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"}