From 47c3f5f0cd6152376c70475c07325b88d8c099c9 Mon Sep 17 00:00:00 2001
From: Lost-Z <manuellost21@gmail.com>
Date: Thu, 30 Jul 2026 10:24:21 +0000
Subject: [PATCH] feat: API response time logging, delivery failure reasons,
 config validation, notification sorting
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes #491
Closes #493
Closes #494
Closes #495

## #491 — Add API Response Time Logging
- New ResponseTimeMiddleware (listener/src/middleware/response-time.ts)
  - Records start time per request via res object symbol key
  - Sets X-Response-Time header on every response
  - Logs completed requests at INFO; flags slow requests at WARN
  - Tracks totalRequests, slowRequests, totalResponseTimeMs, maxResponseTimeMs
  - slowRequestThresholdMs defaults to 1000 ms (configurable via EventsServerOptions)
- Wire middleware into createEventsServer: start() at request open, finish() at 404 fallthrough
- New GET /api/metrics/response-time endpoint exposes counters; ?reset=true resets them

## #493 — Add Delivery Failure Reasons
- NotificationSearchService: add failureReason field to NotificationSearchResult
  - Populated from last_error (scheduled_notifications) and error_reason (processed_events)
- Dashboard eventsApi.ts: expose failureReason on NotificationSearchResult
- NotificationSearchPage: render Failure reason row in NotificationResultCard when present

## #494 — Improve Configuration Validation
- New validateConfig(config) in listener/src/config.ts
  - Validates all critical fields: RPC URL format, port range, poll intervals, scheduler
    lock/batch settings, retry multiplier/delay ordering, rate-limit minimums, analytics
    bucket size, cleanup retention floor
  - Collects all violations before throwing so operators see every problem at once
  - Throws ConfigError with numbered list of descriptive messages
- index.ts: call validateConfig(config) immediately after loadConfig() so invalid
  configuration blocks startup before any service initialises

## #495 — Add Notification Sorting Options
- New NotificationSortOption type (newest | oldest | priority | delivery_status)
  added to dashboard/src/types/event.ts; sortBy field added to EventFilters
- sortEvents() utility in eventData.ts implements all four sort strategies;
  filterEvents() accepts and applies sortBy parameter
- EventFiltersBar: Sort by dropdown persists selection to localStorage via setSortBy
- eventStore: setSortBy action writes to localStorage; loadPersistedSort() restores
  on init; selectFilteredEvents and useFilteredEvents pass sortBy through
- Server-side: NotificationSearchParams.sortBy (newest | oldest | status) added;
  NotificationSearchService.search() applies sort before pagination
- events-server: extracts sortBy query param and forwards to search service
- NotificationSearchPage: Sort by dropdown (newest/oldest/status); included in
  filtersKey so page resets on sort change; cleared by Clear filters
---
 dashboard/src/components/EventFiltersBar.tsx  |  24 +++
 dashboard/src/hooks/useEventSelectors.ts      |   4 +-
 .../src/pages/NotificationSearchPage.tsx      |  28 ++-
 dashboard/src/services/eventsApi.ts           |   8 +
 dashboard/src/store/eventStore.ts             |  33 ++-
 dashboard/src/types/event.ts                  |  12 ++
 dashboard/src/utils/eventData.ts              |  55 ++++-
 listener/src/api/events-server.ts             |  37 ++++
 listener/src/config.ts                        | 199 ++++++++++++++++++
 listener/src/index.ts                         |   5 +-
 listener/src/middleware/response-time.ts      | 149 +++++++++++++
 .../services/notification-search-service.ts   |  45 +++-
 12 files changed, 589 insertions(+), 10 deletions(-)
 create mode 100644 listener/src/middleware/response-time.ts

diff --git a/dashboard/src/components/EventFiltersBar.tsx b/dashboard/src/components/EventFiltersBar.tsx
index a598cf6..8d6f91a 100644
--- a/dashboard/src/components/EventFiltersBar.tsx
+++ b/dashboard/src/components/EventFiltersBar.tsx
@@ -2,6 +2,14 @@ import { memo } from 'react';
 import { useEventStore } from '../store/eventStore';
 import { useEventCount, useEventFilters, useFilterOptions } from '../hooks/useEventSelectors';
 import { SearchAutocomplete } from './SearchAutocomplete';
+import type { NotificationSortOption } from '../types/event';
+
+const SORT_OPTIONS: { value: NotificationSortOption; label: string }[] = [
+  { value: 'newest', label: 'Newest first' },
+  { value: 'oldest', label: 'Oldest first' },
+  { value: 'priority', label: 'Priority (on-chain order)' },
+  { value: 'delivery_status', label: 'Delivery status' },
+];
 
 export const EventFiltersBar = memo(function EventFiltersBar() {
   const filters = useEventFilters();
@@ -10,6 +18,7 @@ export const EventFiltersBar = memo(function EventFiltersBar() {
   const setSearch = useEventStore((state) => state.setSearch);
   const setContractFilter = useEventStore((state) => state.setContractFilter);
   const setEventTypeFilter = useEventStore((state) => state.setEventTypeFilter);
+  const setSortBy = useEventStore((state) => state.setSortBy);
 
   return (
     <section className="event-filters" aria-label="Event filters">
@@ -53,6 +62,21 @@ export const EventFiltersBar = memo(function EventFiltersBar() {
         </select>
       </div>
 
+      {/* Sort control (#495) */}
+      <div className="event-filters__group">
+        <label htmlFor="event-sort">Sort by</label>
+        <select
+          id="event-sort"
+          value={filters.sortBy ?? 'newest'}
+          onChange={(e) => setSortBy(e.target.value as NotificationSortOption)}
+          aria-label="Sort notifications"
+        >
+          {SORT_OPTIONS.map(({ value, label }) => (
+            <option key={value} value={value}>{label}</option>
+          ))}
+        </select>
+      </div>
+
 <p className="event-filters__count" aria-live="polite" role="status">
         {totalCount.toLocaleString()} events loaded
       </p>    </section>
diff --git a/dashboard/src/hooks/useEventSelectors.ts b/dashboard/src/hooks/useEventSelectors.ts
index ba53e31..bac4ed5 100644
--- a/dashboard/src/hooks/useEventSelectors.ts
+++ b/dashboard/src/hooks/useEventSelectors.ts
@@ -16,7 +16,9 @@ export function useFilteredEvents() {
         filters.eventType,
         filters.status,
         filters.dateFrom,
-        filters.dateTo
+        filters.dateTo,
+        filters.txHash,
+        filters.sortBy ?? 'newest',
       ),
     [events, filters]
   );
diff --git a/dashboard/src/pages/NotificationSearchPage.tsx b/dashboard/src/pages/NotificationSearchPage.tsx
index 606fb06..6b36113 100644
--- a/dashboard/src/pages/NotificationSearchPage.tsx
+++ b/dashboard/src/pages/NotificationSearchPage.tsx
@@ -50,6 +50,7 @@ export function NotificationSearchPage() {
   const [dateFrom, setDateFrom] = useState('');
   const [dateTo, setDateTo] = useState('');
   const [page, setPage] = useState(1);
+  const [sortBy, setSortBy] = useState<'newest' | 'oldest' | 'status'>('newest');
 
   const [response, setResponse] = useState<NotificationSearchResponse | null>(null);
   const [loading, setLoading] = useState(false);
@@ -86,6 +87,7 @@ export function NotificationSearchPage() {
       type: type || undefined,
       startDate: dateFrom || undefined,
       endDate: dateTo || undefined,
+      sortBy,
     };
   }, [
     debouncedQuery,
@@ -96,6 +98,7 @@ export function NotificationSearchPage() {
     type,
     dateFrom,
     dateTo,
+    sortBy,
   ]);
 
   const runSearch = useCallback(async () => {
@@ -127,7 +130,7 @@ export function NotificationSearchPage() {
   }, [currentFilters, page, hasParams]);
 
   // Re-run search whenever debounced params change; reset page when filters change
-  const filtersKey = `${debouncedQuery}|${debouncedSender}|${debouncedTxHash}|${debouncedEventId}|${status}|${type}|${dateFrom}|${dateTo}`;
+  const filtersKey = `${debouncedQuery}|${debouncedSender}|${debouncedTxHash}|${debouncedEventId}|${status}|${type}|${dateFrom}|${dateTo}|${sortBy}`;
   const prevFiltersRef = useRef(filtersKey);
   useEffect(() => {
     if (filtersKey !== prevFiltersRef.current) {
@@ -149,6 +152,7 @@ export function NotificationSearchPage() {
     setType('');
     setDateFrom('');
     setDateTo('');
+    setSortBy('newest');
     setPage(1);
     setResponse(null);
     setError(null);
@@ -274,6 +278,22 @@ export function NotificationSearchPage() {
             </select>
           </div>
 
+          {/* Sort control (#495) */}
+          <div className="notif-search-form__group">
+            <label htmlFor="nsf-sort" className="notif-search-form__label">Sort by</label>
+            <select
+              id="nsf-sort"
+              className="notif-search-form__input"
+              value={sortBy}
+              onChange={(e) => setSortBy(e.target.value as 'newest' | 'oldest' | 'status')}
+              aria-label="Sort notifications"
+            >
+              <option value="newest">Newest first</option>
+              <option value="oldest">Oldest first</option>
+              <option value="status">Delivery status</option>
+            </select>
+          </div>
+
           <div className="notif-search-form__group">
             <label htmlFor="nsf-type" className="notif-search-form__label">Notification type</label>
             <select
@@ -497,6 +517,12 @@ function NotificationResultCard({ result }: { result: NotificationSearchResult }
             </dd>
           </>
         )}
+        {result.failureReason && (
+          <>
+            <dt>Failure reason</dt>
+            <dd className="notif-result-card__failure-reason">{result.failureReason}</dd>
+          </>
+        )}
         <dt>Created</dt>
         <dd>{new Date(result.createdAt).toLocaleString()}</dd>
       </dl>
diff --git a/dashboard/src/services/eventsApi.ts b/dashboard/src/services/eventsApi.ts
index eae2ce9..8f5fe5d 100644
--- a/dashboard/src/services/eventsApi.ts
+++ b/dashboard/src/services/eventsApi.ts
@@ -41,6 +41,11 @@ export interface NotificationSearchResult {
   status: string;
   createdAt: string;
   payload: string | null;
+  /**
+   * Human-readable reason the delivery failed (#493).
+   * `null` when the notification succeeded or is still pending.
+   */
+  failureReason: string | null;
 }
 
 export interface NotificationSearchResponse {
@@ -65,6 +70,8 @@ export interface NotificationSearchParams {
   endDate?: string;
   limit?: number;
   offset?: number;
+  /** Sort order for results (#495): newest (default) | oldest | status */
+  sortBy?: 'newest' | 'oldest' | 'status';
 }
 
 export async function fetchEvents(apiUrl: string): Promise<BlockchainEvent[]> {
@@ -101,6 +108,7 @@ export async function searchNotifications(
   if (params.endDate) url.searchParams.set('endDate', params.endDate);
   if (params.limit !== undefined) url.searchParams.set('limit', String(params.limit));
   if (params.offset !== undefined) url.searchParams.set('offset', String(params.offset));
+  if (params.sortBy) url.searchParams.set('sortBy', params.sortBy);
 
   const response = await fetch(url.toString());
   if (!response.ok) {
diff --git a/dashboard/src/store/eventStore.ts b/dashboard/src/store/eventStore.ts
index 8f58bbe..d535890 100644
--- a/dashboard/src/store/eventStore.ts
+++ b/dashboard/src/store/eventStore.ts
@@ -3,6 +3,7 @@ import type {
   BlockchainEvent,
   EventFilters,
   NotificationReadFilter,
+  NotificationSortOption,
   NotificationStatus,
 } from '../types/event';
 import { filterEvents } from '../utils/eventData';
@@ -30,6 +31,11 @@ interface EventStoreState {
   setDateFrom: (dateFrom: string) => void;
   setDateTo: (dateTo: string) => void;
   setTxHashFilter: (txHash: string) => void;
+  /**
+   * Set the active sort order (#495).
+   * The selection is persisted to localStorage so it survives page refreshes.
+   */
+  setSortBy: (sortBy: NotificationSortOption) => void;
   setLoading: (isLoading: boolean) => void;
   setError: (error: string | null) => void;
   /**
@@ -63,6 +69,21 @@ function dedupeEventsById(events: BlockchainEvent[]): BlockchainEvent[] {
   return Array.from(byId.values());
 }
 
+/** Persist the selected sort order across page refreshes. */
+const SORT_STORAGE_KEY = 'notifychain:sortBy';
+
+function loadPersistedSort(): NotificationSortOption {
+  try {
+    const saved = localStorage.getItem(SORT_STORAGE_KEY) as NotificationSortOption | null;
+    if (saved && ['newest', 'oldest', 'priority', 'delivery_status'].includes(saved)) {
+      return saved;
+    }
+  } catch {
+    // localStorage may be unavailable in some environments
+  }
+  return 'newest';
+}
+
 export const useEventStore = create<EventStoreState>((set) => ({
   events: [],
   filters: {
@@ -73,6 +94,7 @@ export const useEventStore = create<EventStoreState>((set) => ({
     dateFrom: '',
     dateTo: '',
     txHash: '',
+    sortBy: loadPersistedSort(),
   },
   isLoading: false,
   error: null,
@@ -97,6 +119,14 @@ export const useEventStore = create<EventStoreState>((set) => ({
     set((state) => ({ filters: { ...state.filters, dateTo } })),
   setTxHashFilter: (txHash) =>
     set((state) => ({ filters: { ...state.filters, txHash } })),
+  setSortBy: (sortBy) => {
+    try {
+      localStorage.setItem(SORT_STORAGE_KEY, sortBy);
+    } catch {
+      // localStorage may be unavailable
+    }
+    set((state) => ({ filters: { ...state.filters, sortBy } }));
+  },
   setLoading: (isLoading) => set({ isLoading }),
   setError: (error) => set({ error }),
   updateEventStatus: (targetEventId, status) =>
@@ -120,7 +150,8 @@ export function selectFilteredEvents(state: EventStoreState): BlockchainEvent[]
     filters.status,
     filters.dateFrom,
     filters.dateTo,
-    filters.txHash
+    filters.txHash,
+    filters.sortBy ?? 'newest',
   );
 }
 
diff --git a/dashboard/src/types/event.ts b/dashboard/src/types/event.ts
index 6d058df..a78f2f4 100644
--- a/dashboard/src/types/event.ts
+++ b/dashboard/src/types/event.ts
@@ -53,6 +53,16 @@ export interface BlockchainEvent {
 /** Read/unread filter for Event Explorer notification lists (not delivery status). */
 export type NotificationReadFilter = 'all' | 'read' | 'unread';
 
+/**
+ * Sort options for the notification list (#495).
+ *
+ * - `newest`          – most recently received first (default)
+ * - `oldest`          – earliest received first
+ * - `priority`        – events with the highest scheduling priority first
+ * - `delivery_status` – group by delivery status (active → expired → revoked → undefined)
+ */
+export type NotificationSortOption = 'newest' | 'oldest' | 'priority' | 'delivery_status';
+
 export interface EventFilters {
   search: string;
   contractAddress: string;
@@ -61,4 +71,6 @@ export interface EventFilters {
   dateFrom: string; // ISO date string "YYYY-MM-DD" or ""
   dateTo: string;   // ISO date string "YYYY-MM-DD" or ""
   txHash?: string;
+  /** Active sort order for the notification list (#495). Defaults to "newest". */
+  sortBy?: NotificationSortOption;
 }
diff --git a/dashboard/src/utils/eventData.ts b/dashboard/src/utils/eventData.ts
index 1db1215..d116843 100644
--- a/dashboard/src/utils/eventData.ts
+++ b/dashboard/src/utils/eventData.ts
@@ -1,4 +1,4 @@
-import type { BlockchainEvent } from '../types/event';
+import type { BlockchainEvent, NotificationSortOption } from '../types/event';
 
 export function generateMockEvents(count: number): BlockchainEvent[] {
   const eventNames = [
@@ -32,6 +32,52 @@ export function generateMockEvents(count: number): BlockchainEvent[] {
   });
 }
 
+/**
+ * Sort comparator for blockchain events (#495).
+ *
+ * - newest          – most recently received first (default, matches previous behaviour)
+ * - oldest          – earliest received first
+ * - priority        – lower ledger number first (on-chain ordering proxy), then newest within ledger
+ * - delivery_status – active → expired → revoked → undefined, then newest within each bucket
+ */
+export function sortEvents(
+  events: BlockchainEvent[],
+  sortBy: NotificationSortOption = 'newest',
+): BlockchainEvent[] {
+  const STATUS_ORDER: Record<string, number> = {
+    active: 0,
+    expired: 1,
+    revoked: 2,
+  };
+
+  const copy = [...events];
+
+  switch (sortBy) {
+    case 'oldest':
+      return copy.sort((a, b) => a.receivedAt - b.receivedAt);
+
+    case 'priority':
+      // Lower ledger number = earlier on-chain = higher priority; break ties newest-first
+      return copy.sort((a, b) => {
+        const ledgerDiff = a.ledger - b.ledger;
+        if (ledgerDiff !== 0) return ledgerDiff;
+        return b.receivedAt - a.receivedAt;
+      });
+
+    case 'delivery_status':
+      return copy.sort((a, b) => {
+        const sa = STATUS_ORDER[a.notificationStatus ?? ''] ?? 3;
+        const sb = STATUS_ORDER[b.notificationStatus ?? ''] ?? 3;
+        if (sa !== sb) return sa - sb;
+        return b.receivedAt - a.receivedAt;
+      });
+
+    case 'newest':
+    default:
+      return copy.sort((a, b) => b.receivedAt - a.receivedAt);
+  }
+}
+
 export function filterEvents(
   events: BlockchainEvent[],
   search: string,
@@ -40,7 +86,8 @@ export function filterEvents(
   status: import('../types/event').NotificationReadFilter = 'all',
   dateFrom = '',
   dateTo = '',
-  txHash = ''
+  txHash = '',
+  sortBy: NotificationSortOption = 'newest',
 ): BlockchainEvent[] {
   const normalizedSearch = search.trim().toLowerCase();
   const normalizedTxHash = txHash.trim().toLowerCase();
@@ -48,7 +95,7 @@ export function filterEvents(
   // dateTo is inclusive: include the entire day
   const toMs = dateTo ? new Date(dateTo).getTime() + 86_399_999 : Infinity;
 
-  return events.filter((event) => {
+  const filtered = events.filter((event) => {
     if (contractAddress !== 'all' && event.contractAddress !== contractAddress) return false;
     if (eventType !== 'all' && event.eventName !== eventType) return false;
 
@@ -68,4 +115,6 @@ export function filterEvents(
       event.txHash?.toLowerCase().includes(normalizedSearch)
     );
   });
+
+  return sortEvents(filtered, sortBy);
 }
diff --git a/listener/src/api/events-server.ts b/listener/src/api/events-server.ts
index bf23268..50c0efc 100644
--- a/listener/src/api/events-server.ts
+++ b/listener/src/api/events-server.ts
@@ -51,6 +51,7 @@ import { NotificationMetricsStore } from '../services/notification-metrics-store
 import { NotificationHealthMonitor } from '../services/notification-health-monitor';
 import { getJobMonitor } from '../services/job-monitor';
 import { NotificationImportService } from '../services/notification-import-service';
+import { ResponseTimeMiddleware } from '../middleware/response-time';
 
 export interface EventsServerOptions {
   port: number;
@@ -81,6 +82,16 @@ export interface EventsServerOptions {
   signatureExpirationSeconds?: number;
   /** Optional health monitor — exposes its last report at GET /api/notifications/health. */
   healthMonitor?: NotificationHealthMonitor | null;
+  /**
+   * Requests slower than this threshold (ms) are logged at WARN level (#491).
+   * Defaults to 1 000 ms.
+   */
+  slowRequestThresholdMs?: number;
+  /**
+   * Override the ResponseTimeMiddleware instance — primarily for testing.
+   * When omitted a new instance is created using `slowRequestThresholdMs`.
+   */
+  responseTimeMiddleware?: ResponseTimeMiddleware | null;
 }
 
 type ServiceStatus = 'ok' | 'error' | 'not_configured';
@@ -402,12 +413,20 @@ export function createEventsServer(options: EventsServerOptions): http.Server {
   const suggestionService = new SearchSuggestionService();
   const notificationSearchService = new NotificationSearchService();
   const rateLimiter = options.rateLimit ? new RateLimiter(options.rateLimit) : undefined;
+  // Response-time tracking (#491)
+  const responseTime =
+    options.responseTimeMiddleware !== undefined && options.responseTimeMiddleware !== null
+      ? options.responseTimeMiddleware
+      : new ResponseTimeMiddleware({ slowRequestThresholdMs: options.slowRequestThresholdMs });
 
   const server = http.createServer(async (req, res) => {
     const requestId = generateRequestId();
     const correlationId = resolveCorrelationId(req.headers['x-correlation-id']);
     const startTime = Date.now();
 
+    // Start response-time tracking for this request (#491)
+    responseTime.start(res);
+
     res.setHeader('Access-Control-Allow-Origin', corsOrigin);
     res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
     res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
@@ -1080,6 +1099,8 @@ export function createEventsServer(options: EventsServerOptions): http.Server {
       const endDate = url.searchParams.get('endDate') ?? undefined;
       const limit = url.searchParams.get('limit') ? parseInt(url.searchParams.get('limit')!, 10) : undefined;
       const offset = url.searchParams.get('offset') ? parseInt(url.searchParams.get('offset')!, 10) : undefined;
+      const rawSortBy = url.searchParams.get('sortBy') ?? undefined;
+      const sortBy = (rawSortBy === 'oldest' || rawSortBy === 'status') ? rawSortBy : 'newest';
 
       logger.info('Handling GET /api/notifications/search', {
         requestId,
@@ -1094,6 +1115,7 @@ export function createEventsServer(options: EventsServerOptions): http.Server {
         endDate,
         limit,
         offset,
+        sortBy,
       });
 
       notificationSearchService.search({
@@ -1107,6 +1129,7 @@ export function createEventsServer(options: EventsServerOptions): http.Server {
         endDate,
         limit,
         offset,
+        sortBy,
       })
         .then((result) => {
           res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -1509,6 +1532,19 @@ export function createEventsServer(options: EventsServerOptions): http.Server {
       if (handled) return;
     }
 
+    // GET /api/metrics/response-time — expose response-time counters (#491)
+    if (req.method === 'GET' && url.pathname === '/api/metrics/response-time') {
+      const metrics = responseTime.getMetrics();
+      const reset = url.searchParams.get('reset') === 'true';
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(metrics));
+      if (reset) {
+        responseTime.resetMetrics();
+        logger.info('Response-time metrics reset', { requestId });
+      }
+      return;
+    }
+
     logger.warn('Unhandled request', {
       requestId,
       method: req.method,
@@ -1516,6 +1552,7 @@ export function createEventsServer(options: EventsServerOptions): http.Server {
     });
     res.writeHead(404, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify({ error: 'Not found' }));
+    responseTime.finish(req, res, requestId, 404);
   });
 
   if (rateLimiter) {
diff --git a/listener/src/config.ts b/listener/src/config.ts
index fe5c962..f0ce69c 100644
--- a/listener/src/config.ts
+++ b/listener/src/config.ts
@@ -231,3 +231,202 @@ export function loadConfig(): Config {
   };
 }
 
+/**
+ * Validate a fully-loaded Config object and throw a descriptive ConfigError
+ * for every invalid value found.  Call this immediately after `loadConfig()`
+ * so that misconfigured services never start processing events (#494).
+ *
+ * All violations are collected before throwing so operators see every problem
+ * in a single error message rather than having to fix-and-restart repeatedly.
+ */
+export function validateConfig(config: Config): void {
+  const errors: string[] = [];
+
+  // ── Network ────────────────────────────────────────────────────────────────
+  if (!config.stellarRpcUrl || !config.stellarRpcUrl.startsWith('http')) {
+    errors.push(
+      'STELLAR_RPC_URL must be a valid HTTP/HTTPS URL ' +
+        `(received: "${config.stellarRpcUrl}").`,
+    );
+  }
+
+  if (!config.stellarNetworkPassphrase || config.stellarNetworkPassphrase.trim() === '') {
+    errors.push('STELLAR_NETWORK_PASSPHRASE must be a non-empty string.');
+  }
+
+  // ── Polling ────────────────────────────────────────────────────────────────
+  if (config.pollIntervalMs < 1000) {
+    errors.push(
+      `POLL_INTERVAL_MS must be at least 1000 ms to avoid excessive RPC load ` +
+        `(received: ${config.pollIntervalMs}).`,
+    );
+  }
+
+  if (config.maxReconnectAttempts < 1) {
+    errors.push(
+      `MAX_RECONNECT_ATTEMPTS must be >= 1 (received: ${config.maxReconnectAttempts}).`,
+    );
+  }
+
+  if (config.reconnectDelayMs < 0) {
+    errors.push(
+      `RECONNECT_DELAY_MS must be >= 0 (received: ${config.reconnectDelayMs}).`,
+    );
+  }
+
+  // ── API server ─────────────────────────────────────────────────────────────
+  if (config.eventsApiPort < 1 || config.eventsApiPort > 65535) {
+    errors.push(
+      `EVENTS_API_PORT must be between 1 and 65535 (received: ${config.eventsApiPort}).`,
+    );
+  }
+
+  // ── Contract addresses ─────────────────────────────────────────────────────
+  if (!Array.isArray(config.contractAddresses)) {
+    errors.push('CONTRACT_ADDRESSES must be a JSON array.');
+  } else {
+    config.contractAddresses.forEach((contract, index) => {
+      if (!contract.address || typeof contract.address !== 'string') {
+        errors.push(`CONTRACT_ADDRESSES[${index}].address must be a non-empty string.`);
+      }
+      if (!Array.isArray(contract.events) || contract.events.length === 0) {
+        errors.push(
+          `CONTRACT_ADDRESSES[${index}].events must be a non-empty array of event names.`,
+        );
+      }
+    });
+  }
+
+  // ── Discord ────────────────────────────────────────────────────────────────
+  if (config.discord) {
+    if (!config.discord.webhookUrl.startsWith('https://discord.com/api/webhooks/')) {
+      errors.push(
+        'DISCORD_WEBHOOK_URL must start with "https://discord.com/api/webhooks/". ' +
+          'Verify the URL copied from Discord server settings.',
+      );
+    }
+    if (!config.discord.webhookId || config.discord.webhookId.trim() === '') {
+      errors.push('DISCORD_WEBHOOK_ID must be a non-empty string.');
+    }
+    if (
+      config.discord.deduplicationWindowMs !== undefined &&
+      config.discord.deduplicationWindowMs < 0
+    ) {
+      errors.push(
+        `NOTIFICATION_DEDUPLICATION_WINDOW_MS must be >= 0 ` +
+          `(received: ${config.discord.deduplicationWindowMs}).`,
+      );
+    }
+  }
+
+  // ── Scheduler ─────────────────────────────────────────────────────────────
+  if (config.scheduler) {
+    if (config.scheduler.pollIntervalMs < 1000) {
+      errors.push(
+        `SCHEDULER_POLL_INTERVAL_MS must be >= 1000 ms ` +
+          `(received: ${config.scheduler.pollIntervalMs}).`,
+      );
+    }
+    if (config.scheduler.lockTimeoutMs < config.scheduler.pollIntervalMs) {
+      errors.push(
+        'SCHEDULER_LOCK_TIMEOUT_MS must be >= SCHEDULER_POLL_INTERVAL_MS to avoid ' +
+          'premature lock expiry. Increase SCHEDULER_LOCK_TIMEOUT_MS or reduce ' +
+          'SCHEDULER_POLL_INTERVAL_MS.',
+      );
+    }
+    if (config.scheduler.batchSize < 1) {
+      errors.push(`SCHEDULER_BATCH_SIZE must be >= 1 (received: ${config.scheduler.batchSize}).`);
+    }
+  }
+
+  // ── Retry scheduler ────────────────────────────────────────────────────────
+  if (config.retryScheduler) {
+    if (config.retryScheduler.pollIntervalMs < 1000) {
+      errors.push(
+        `RETRY_SCHEDULER_POLL_INTERVAL_MS must be >= 1000 ms ` +
+          `(received: ${config.retryScheduler.pollIntervalMs}).`,
+      );
+    }
+    if (config.retryScheduler.baseDelayMs < 0) {
+      errors.push(
+        `RETRY_BASE_DELAY_MS must be >= 0 (received: ${config.retryScheduler.baseDelayMs}).`,
+      );
+    }
+    if (config.retryScheduler.multiplier < 1) {
+      errors.push(
+        `RETRY_MULTIPLIER must be >= 1 (received: ${config.retryScheduler.multiplier}). ` +
+          'A multiplier below 1 would cause retry delays to shrink, not grow.',
+      );
+    }
+    if (config.retryScheduler.maxDelayMs < config.retryScheduler.baseDelayMs) {
+      errors.push(
+        'RETRY_MAX_DELAY_MS must be >= RETRY_BASE_DELAY_MS. ' +
+          `Received max=${config.retryScheduler.maxDelayMs}, base=${config.retryScheduler.baseDelayMs}.`,
+      );
+    }
+    if (config.retryScheduler.batchSize < 1) {
+      errors.push(
+        `RETRY_SCHEDULER_BATCH_SIZE must be >= 1 (received: ${config.retryScheduler.batchSize}).`,
+      );
+    }
+  }
+
+  // ── Rate limiting ──────────────────────────────────────────────────────────
+  if (config.rateLimit) {
+    if (config.rateLimit.windowMs < 1000) {
+      errors.push(
+        `RATE_LIMIT_WINDOW_MS must be >= 1000 ms (received: ${config.rateLimit.windowMs}).`,
+      );
+    }
+    if (config.rateLimit.maxRequests < 1) {
+      errors.push(
+        `RATE_LIMIT_MAX_REQUESTS must be >= 1 (received: ${config.rateLimit.maxRequests}).`,
+      );
+    }
+  }
+
+  // ── Analytics ─────────────────────────────────────────────────────────────
+  if (config.analytics) {
+    if (config.analytics.maxRecords < 1) {
+      errors.push(
+        `ANALYTICS_MAX_RECORDS must be >= 1 (received: ${config.analytics.maxRecords}).`,
+      );
+    }
+    if (config.analytics.bucketSizeMs < 60_000) {
+      errors.push(
+        `ANALYTICS_BUCKET_SIZE_MS must be >= 60000 ms (1 minute) ` +
+          `(received: ${config.analytics.bucketSizeMs}).`,
+      );
+    }
+    if (config.analytics.snapshotRetentionDays < 1) {
+      errors.push(
+        `ANALYTICS_SNAPSHOT_RETENTION_DAYS must be >= 1 ` +
+          `(received: ${config.analytics.snapshotRetentionDays}).`,
+      );
+    }
+  }
+
+  // ── Cleanup ────────────────────────────────────────────────────────────────
+  if (config.cleanup) {
+    if (config.cleanup.intervalMs < 60_000) {
+      errors.push(
+        `CLEANUP_INTERVAL_MS must be >= 60000 ms (1 minute) ` +
+          `(received: ${config.cleanup.intervalMs}).`,
+      );
+    }
+    if (config.cleanup.notificationRetentionMs < 60_000) {
+      errors.push(
+        `NOTIFICATION_RETENTION_MS must be >= 60000 ms ` +
+          `(received: ${config.cleanup.notificationRetentionMs}).`,
+      );
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new ConfigError(
+      `Configuration validation failed with ${errors.length} error(s):\n` +
+        errors.map((e, i) => `  ${i + 1}. ${e}`).join('\n'),
+    );
+  }
+}
+
diff --git a/listener/src/index.ts b/listener/src/index.ts
index 54e9e6b..987413a 100644
--- a/listener/src/index.ts
+++ b/listener/src/index.ts
@@ -28,7 +28,7 @@ import { NotificationMetricsStore } from './services/notification-metrics-store'
 import { NotificationMetricsRunner } from './services/notification-metrics-runner';
 import { eventRegistry } from './store/event-registry';
 import logger from './utils/logger';
-import { loadConfig, ConfigError } from './config';
+import { loadConfig, validateConfig, ConfigError } from './config';
 import { NotificationHealthMonitor } from './services/notification-health-monitor';
 import { getWorkerManager } from './services/worker-manager';
 
@@ -36,6 +36,9 @@ dotenv.config();
 
 async function main() {
   const config = loadConfig();
+  // Validate all config values before starting any services (#494).
+  // This throws a descriptive ConfigError listing every problem found.
+  validateConfig(config);
 
   // Initialize database for scheduled notifications and templates
   // Initialize database for templates, scheduler, and rate limiting
diff --git a/listener/src/middleware/response-time.ts b/listener/src/middleware/response-time.ts
new file mode 100644
index 0000000..20c5d52
--- /dev/null
+++ b/listener/src/middleware/response-time.ts
@@ -0,0 +1,149 @@
+/**
+ * Response-time middleware (#491)
+ *
+ * Attaches an `X-Response-Time` header to every HTTP response and logs the
+ * elapsed milliseconds.  Requests that exceed `slowRequestThresholdMs` are
+ * flagged at WARN level so they are easy to spot in log aggregators.
+ *
+ * Usage:
+ *
+ *   const rt = new ResponseTimeMiddleware({ slowRequestThresholdMs: 1000 });
+ *   // early in the request handler:
+ *   rt.start(res);
+ *   // just before writing the status line:
+ *   rt.finish(req, res, requestId);
+ */
+
+import http from 'http';
+import logger from '../utils/logger';
+
+export interface ResponseTimeOptions {
+  /**
+   * Requests slower than this value (ms) are logged at WARN level and flagged
+   * as slow.  Defaults to 1 000 ms.
+   */
+  slowRequestThresholdMs?: number;
+}
+
+export interface ResponseTimeMetrics {
+  totalRequests: number;
+  slowRequests: number;
+  /** Sum of all response times in ms — divide by totalRequests for the mean. */
+  totalResponseTimeMs: number;
+  maxResponseTimeMs: number;
+}
+
+const START_TIME_KEY = Symbol('responseTimeStart');
+
+export class ResponseTimeMiddleware {
+  private readonly threshold: number;
+  private metrics: ResponseTimeMetrics = {
+    totalRequests: 0,
+    slowRequests: 0,
+    totalResponseTimeMs: 0,
+    maxResponseTimeMs: 0,
+  };
+
+  constructor(options: ResponseTimeOptions = {}) {
+    this.threshold = options.slowRequestThresholdMs ?? 1_000;
+  }
+
+  /**
+   * Call at the very start of request processing to record the start time.
+   * The timestamp is stored on the response object so it travels through the
+   * handler stack without needing a separate closure.
+   */
+  start(res: http.ServerResponse): void {
+    (res as any)[START_TIME_KEY] = Date.now();
+  }
+
+  /**
+   * Call just before sending the response.  Computes the elapsed time, sets
+   * the `X-Response-Time` header, logs the result, and updates metrics.
+   *
+   * Returns the elapsed time in ms so callers can include it in their own log
+   * entries.
+   */
+  finish(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    requestId?: string,
+    statusCode?: number,
+  ): number {
+    const startTime = (res as any)[START_TIME_KEY] as number | undefined;
+    const durationMs = startTime !== undefined ? Date.now() - startTime : 0;
+
+    // Attach the timing header before the caller calls writeHead so the value
+    // is available on the wire.  If headers have already been sent this is a
+    // no-op (Node.js silently ignores setHeader after headers flush).
+    if (!res.headersSent) {
+      res.setHeader('X-Response-Time', `${durationMs}ms`);
+    }
+
+    const method = req.method ?? 'UNKNOWN';
+    const url = req.url ?? '/';
+    const status = statusCode ?? res.statusCode;
+    const isSlow = durationMs >= this.threshold;
+
+    // Update in-memory metrics
+    this.metrics.totalRequests += 1;
+    this.metrics.totalResponseTimeMs += durationMs;
+    if (durationMs > this.metrics.maxResponseTimeMs) {
+      this.metrics.maxResponseTimeMs = durationMs;
+    }
+    if (isSlow) {
+      this.metrics.slowRequests += 1;
+    }
+
+    const meta: Record<string, unknown> = {
+      method,
+      url,
+      statusCode: status,
+      durationMs,
+      ...(requestId ? { requestId } : {}),
+    };
+
+    if (isSlow) {
+      logger.warn('Slow request detected', {
+        ...meta,
+        slowThresholdMs: this.threshold,
+      });
+    } else {
+      logger.info('Request completed', meta);
+    }
+
+    return durationMs;
+  }
+
+  /** Returns a snapshot of the accumulated response-time metrics. */
+  getMetrics(): ResponseTimeMetrics {
+    return { ...this.metrics };
+  }
+
+  /** Resets accumulated metrics back to zero. */
+  resetMetrics(): void {
+    this.metrics = {
+      totalRequests: 0,
+      slowRequests: 0,
+      totalResponseTimeMs: 0,
+      maxResponseTimeMs: 0,
+    };
+  }
+}
+
+/** Process-wide singleton so multiple modules share the same counters. */
+let instance: ResponseTimeMiddleware | null = null;
+
+export function getResponseTimeMiddleware(
+  options?: ResponseTimeOptions,
+): ResponseTimeMiddleware {
+  if (!instance) {
+    instance = new ResponseTimeMiddleware(options);
+  }
+  return instance;
+}
+
+/** Replace the singleton — primarily used in tests. */
+export function setResponseTimeMiddleware(mw: ResponseTimeMiddleware): void {
+  instance = mw;
+}
diff --git a/listener/src/services/notification-search-service.ts b/listener/src/services/notification-search-service.ts
index 8ad90ed..ec34ee0 100644
--- a/listener/src/services/notification-search-service.ts
+++ b/listener/src/services/notification-search-service.ts
@@ -13,6 +13,13 @@ export interface NotificationSearchParams {
   endDate?: string;   // inclusive upper bound on created_at / processed_at (YYYY-MM-DD or ISO)
   limit?: number;
   offset?: number;
+  /**
+   * Sort order for results (#495).
+   * - newest (default) – most recently created first
+   * - oldest           – earliest created first
+   * - status           – group by delivery status, then newest within each group
+   */
+  sortBy?: 'newest' | 'oldest' | 'status';
 }
 
 /** Normalize a date filter so YYYY-MM-DD covers the full UTC day. */
@@ -32,6 +39,13 @@ export interface NotificationSearchResult {
   status: string;
   createdAt: string;
   payload: string | null;
+  /**
+   * Human-readable reason the delivery failed (#493).
+   * Populated from `last_error` for scheduled notifications and from
+   * `error_message` for processed events.  `null` when the notification
+   * succeeded or is still pending.
+   */
+  failureReason: string | null;
 }
 
 export interface PaginatedSearchResponse {
@@ -56,7 +70,28 @@ export class NotificationSearchService {
 
       // Merge, sort by createdAt desc, then re-paginate
       const merged = [...scheduledResults.rows, ...processedResults.rows].sort(
-        (a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()
+        (a, b) => {
+          const sortBy = params.sortBy ?? 'newest';
+          if (sortBy === 'oldest') {
+            return new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime();
+          }
+          if (sortBy === 'status') {
+            const STATUS_ORDER: Record<string, number> = {
+              PENDING: 0,
+              PROCESSING: 1,
+              COMPLETED: 2,
+              FAILED: 3,
+              CANCELLED: 4,
+              PROCESSED: 5,
+            };
+            const sa = STATUS_ORDER[a.status.toUpperCase()] ?? 99;
+            const sb = STATUS_ORDER[b.status.toUpperCase()] ?? 99;
+            if (sa !== sb) return sa - sb;
+            return new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime();
+          }
+          // default: newest
+          return new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime();
+        }
       );
       const total = scheduledResults.total + processedResults.total;
 
@@ -137,8 +172,9 @@ export class NotificationSearchService {
       status: string;
       created_at: string;
       payload: string;
+      last_error: string | null;
     }>(
-      `SELECT id, event_id, contract_address, notification_type, target_recipient, status, created_at, payload
+      `SELECT id, event_id, contract_address, notification_type, target_recipient, status, created_at, payload, last_error
        FROM scheduled_notifications ${where}
        ORDER BY created_at DESC
        LIMIT ? OFFSET ?`,
@@ -158,6 +194,7 @@ export class NotificationSearchService {
         status: r.status,
         createdAt: r.created_at,
         payload: r.payload,
+        failureReason: r.last_error ?? null,
       })),
     };
   }
@@ -221,8 +258,9 @@ export class NotificationSearchService {
       event_type: string;
       status: string;
       processed_at: string;
+      error_reason: string | null;
     }>(
-      `SELECT id, event_id, tx_hash, contract_address, event_type, status, processed_at
+      `SELECT id, event_id, tx_hash, contract_address, event_type, status, processed_at, error_reason
        FROM processed_events ${where}
        ORDER BY processed_at DESC
        LIMIT ? OFFSET ?`,
@@ -242,6 +280,7 @@ export class NotificationSearchService {
         status: r.status,
         createdAt: r.processed_at,
         payload: null,
+        failureReason: r.error_reason ?? null,
       })),
     };
   }