AdminReviewManager

Enhanced admin review functionality for Trade Fund applications including remarks, audit logging, bulk operations, and cursor-based listing.

Purpose

AdminReviewManager is a read-heavy, admin-facing manager that provides the tooling admins need to review Trade Fund applications. It does not own the application lifecycle (that's ApplicationManager), but adds: eligibility calculation, append-only remarks, audit logging, advanced listing, and bulk operations.

High-Level Design

Role: Query & Annotate Layer

AdminReviewManager reads application data that other managers create and provides admin-specific operations on top. It never transitions application status directly — bulk approve/reject delegates back to the parent DO (TradeFundAccountRegistry), which orchestrates across managers.

Admin Request
     │
     ▼
AdminReviewManager
     │
     ├─ Read operations (list, eligibility, remarks, audit logs)
     │    → Queries shared SQLite tables directly
     │
     └─ Write operations (bulk approve/reject, add remark)
          │
          ├─ Remarks/audit → Writes to own tables
          │
          └─ Status changes → Delegates to parent DO
               │
               ▼
          TradeFundAccountRegistry (orchestrator)
               └─ See ApplicationManager for full approval flow

Delegation Pattern

Bulk operations call this.durable.approveApplication() / this.durable.rejectTradeFundApplication() rather than calling sibling managers directly. This keeps the parent DO as the single orchestration point for status transitions, preserving clear responsibility boundaries.

Eligibility Calculation

Pure function that evaluates challenge criteria (C1: profit target, C2: consistency, C3: trading days) and returns "eligible", "contender" (within 2% of consistency target), or "N/A". Used to annotate applications for admin review — no side effects.

Append-Only Remarks

Admin notes attached to applications, organized by stage (review, monitor, payout). Remarks are immutable once created (no edit/delete) for compliance. Each remark can optionally link to a challengeRecordId, payoutId, or applicationId via secondary keys. All content is HTML-sanitized to prevent XSS.

Cursor-Based Pagination (Keyset)

The enhanced listing uses keyset pagination instead of offset-based, which is resilient to concurrent modifications and efficient for large datasets.

Key design decisions:

• Cursor encodes sort context: sort column, direction, sort value, created_at tiebreaker, and UUID tiebreaker. Cursors from a different sort configuration are rejected.
• NULL handling: NULLs always sort last regardless of ASC/DESC via custom SQL conditions.
• Overfetch for programmatic filters: userIds and walletAddresses use substring matching that can't be expressed efficiently in SQL. When these filters are active, the system fetches 3× the requested limit from SQL and filters in-memory. total reflects SQL filters only (not programmatic ones).
• Sort column whitelist: Uses a Map (VALID_SORT_COLUMNS) to map sort keys to SQL columns, preventing injection.

Bulk Operations

Pre-validate all IDs (UUID v4 format + existence) before processing. Each application is processed individually — one failure does not block others. Capped at 50 per batch. A summary audit entry records succeeded/failed counts.

Edge Cases & Error Handling

• Sort column uses a whitelist map (VALID_SORT_COLUMNS) to prevent SQL injection.
• Cursor is validated against the current sort context (sort column + direction); mismatched cursors are rejected.
• NULL sort values are ordered last in both ASC and DESC via custom cursor conditions.
• Remarks are HTML-sanitized with escapeHtml() to prevent XSS.
• Application IDs are validated as UUID v4 format before database lookup.
• Bulk operations process each application individually for error isolation (one failure does not block others).
• total count excludes cursor conditions for accurate pagination metadata.
• Date range from > to throws INVALID_DATE_RANGE.
• Remark secondaryKeyValue required when secondaryKey is provided.
• Bulk rejection requires a non-empty reason string.

See Also

• ApplicationManager - Core application lifecycle (create, reject, approve).
• MasterAccountManager - Hyperliquid master/agent account creation.
• MonitoringManager - Account health monitoring.
• PayoutManager - Payout request lifecycle.
• Parent DO: TradeFundAccountRegistry