refactor(web): narrow analytics route response boundaries

Author: devstd2211

ACTIVE_REFACTOR_PLAN.md

@@ -41,24 +41,24 @@ Historical detail is archived elsewhere and should not be copied here.
 9. Do not run separate test-only cleanup campaigns.
 
 ## Latest Completed
-- 2026-06-03: completed `packages/web-server/tests/web-server.functional.test.ts web server route adapter composition guardrail follow-up`.
-- 2026-06-03: completed `packages/web-server/src/websocket/ws-server.ts websocket bridge runtime adapter boundary follow-up`.
-- 2026-06-03: completed `packages/web-server/tests/ws-server.functional.test.ts websocket bridge runtime adapter functional guardrail follow-up`.
-- `ws-server.ts` now consumes an explicit `WebSocketBridgeApi` instead of the concrete `BotBridgeService`, so websocket reads and `bot-event` subscriptions cross one narrowed runtime adapter seam.
-- `index.ts` now composes route dependencies and websocket delegates through `createWebServerRuntimeDependencies(...)`, keeping runtime wiring in one place before `WebServer` starts sockets and file-watchers.
-- `web-server.functional.test.ts` now guards that the web-server runtime bundle carries both explicit route dependencies and the shared websocket delegate surface.
-- `ws-server.functional.test.ts` now proves the websocket bridge adapter preserves status reads, position reads, and `bot-event` unsubscribe behavior independent of the concrete bridge class.
+- 2026-06-03: completed `packages/web-server/src/routes/analytics.routes.ts analytics route runtime adapter boundary follow-up`.
+- 2026-06-03: completed `packages/web-server/src/routes/route-response.ts web server shared route response runtime boundary follow-up`.
+- 2026-06-03: completed `packages/web-server/src/routes/analytics.constants.ts analytics route runtime constants boundary follow-up`.
+- `analytics.routes.ts` now consumes an explicit route dependency bundle split into `journal`, `sessions`, `strategy`, and `curves`, so the HTTP layer no longer depends on one flat file-watcher-shaped read surface.
+- `analytics.constants.ts` now owns analytics route paging, recent-window, and fallback-message constants instead of leaving route magic numbers and fallback strings inline.
+- `route-response.ts` now builds an explicit route response context before writing success or error envelopes, keeping request-id normalization and shared route execution behavior on one runtime seam.
+- `route-response.test.ts` now guards the shared response helper directly, while `web-server.functional.test.ts` proves the analytics route bundle stays on the narrowed delegates.
 
 ## Latest Verification
+- 2026-06-03: `npm test -- --runInBand packages/web-server/tests/route-response.test.ts` (1 suite, 4 tests)
 - 2026-06-03: `npm test -- --runInBand packages/web-server/tests/web-server.functional.test.ts` (1 suite, 53 tests)
-- 2026-06-03: `npm test -- --runInBand packages/web-server/tests/ws-server.functional.test.ts` (1 suite, 21 tests)
 - 2026-06-03: `npm test -- --runInBand position-monitor` (6 suites, 59 tests)
 - 2026-06-03: `npm run build`
 
 ## Next Step
 - Continue with the next active component from `REFACTOR_COMPONENT_CHECKLIST.md`.
-- Start with `packages/web-server/src/routes/analytics.routes.ts analytics route runtime adapter boundary follow-up`.
-- Keep the next batch on the web-server runtime/error boundary stream before returning to the remaining docs guardrail items.
+- Start with `packages/web-server/src/swagger.config.ts web server OpenAPI contract surface boundary follow-up`.
+- Keep the next batch on the web-server runtime/error boundary stream before returning to the remaining core docs guardrail items.
 
 ## Archive
 - Frozen archive of the previous oversized active plan: `REFACTOR_PLAN_01.md`

NEXT_SESSION_PROMPT.md

@@ -14,9 +14,9 @@ Work directly on local `main`. Do not create worktrees. If the current branch is
 
 ## Current Batch
 Start with these three active queue items:
-1. `packages/web-server/src/routes/analytics.routes.ts analytics route runtime adapter boundary follow-up`
-2. `packages/web-server/src/routes/route-response.ts web server shared route response runtime boundary follow-up`
-3. `packages/web-server/src/routes/analytics.constants.ts analytics route runtime constants boundary follow-up`
+1. `packages/web-server/src/swagger.config.ts web server OpenAPI contract surface boundary follow-up`
+2. `packages/web-server/src/runtime-discovery-guidance.ts web server runtime discovery guidance boundary follow-up`
+3. `packages/web-server/src/middleware/request-logging.middleware.ts web server runtime logging boundary follow-up`
 
 If one of these turns out to be too small, merge it with the next adjacent runtime,
 initializer, or websocket boundary item from `REFACTOR_COMPONENT_CHECKLIST.md` and keep
@@ -53,15 +53,15 @@ After all three slices are complete:
 5. Commit the batch after tests, smoke, build, and docs updates pass.
 
 ## Last Completed
-- 2026-06-03: completed `packages/web-server/tests/web-server.functional.test.ts web server route adapter composition guardrail follow-up`.
-- 2026-06-03: completed `packages/web-server/src/websocket/ws-server.ts websocket bridge runtime adapter boundary follow-up`.
-- 2026-06-03: completed `packages/web-server/tests/ws-server.functional.test.ts websocket bridge runtime adapter functional guardrail follow-up`.
-- `ws-server.ts` now depends on an explicit `WebSocketBridgeApi` seam for status reads, position reads, and `bot-event` forwarding instead of binding directly to the concrete bridge service.
-- `index.ts` now composes route dependencies and websocket delegates through `createWebServerRuntimeDependencies(...)`, keeping runtime ownership explicit before startup.
-- `web-server.functional.test.ts` and `ws-server.functional.test.ts` now guard the shared websocket delegate seam, including unsubscribe behavior and runtime bundle wiring.
+- 2026-06-03: completed `packages/web-server/src/routes/analytics.routes.ts analytics route runtime adapter boundary follow-up`.
+- 2026-06-03: completed `packages/web-server/src/routes/route-response.ts web server shared route response runtime boundary follow-up`.
+- 2026-06-03: completed `packages/web-server/src/routes/analytics.constants.ts analytics route runtime constants boundary follow-up`.
+- `analytics.routes.ts` now depends on a nested analytics route bundle (`journal`, `sessions`, `strategy`, `curves`) instead of a flat file-watcher-shaped read surface.
+- `analytics.constants.ts` now owns route defaults and fallback strings for analytics paging, recent-history reads, and curve endpoints.
+- `route-response.ts` now creates an explicit route response context before writing shared success/error envelopes, and `route-response.test.ts` directly guards request-id normalization plus fallback error behavior.
 
 ## Last Verification
+- `npm test -- --runInBand packages/web-server/tests/route-response.test.ts`
 - `npm test -- --runInBand packages/web-server/tests/web-server.functional.test.ts`
-- `npm test -- --runInBand packages/web-server/tests/ws-server.functional.test.ts`
 - `npm test -- --runInBand position-monitor`
 - `npm run build`

REFACTOR_COMPONENT_CHECKLIST.md

@@ -15,23 +15,26 @@ Legend:
 - `func` = functional test exists
 
 ## Active Components
-- [ ] `packages/web-server/src/routes/analytics.routes.ts analytics route runtime adapter boundary follow-up`
-- [ ] `packages/web-server/src/routes/route-response.ts web server shared route response runtime boundary follow-up`
-- [ ] `packages/web-server/src/routes/analytics.constants.ts analytics route runtime constants boundary follow-up`
 - [ ] `packages/web-server/src/swagger.config.ts web server OpenAPI contract surface boundary follow-up`
 - [ ] `packages/web-server/src/runtime-discovery-guidance.ts web server runtime discovery guidance boundary follow-up`
-- [ ] `packages/core/src/__tests__/web/web-boundary.test.ts web server adapter contract guardrail follow-up`
-- [ ] `packages/core/src/__tests__/core/readme-entrypoint-boundary.functional.test.ts runtime handoff docs guardrail follow-up`
-- [ ] `packages/core/src/__tests__/core/architecture-entrypoint-boundary.functional.test.ts runtime handoff docs guardrail follow-up`
-- [ ] `packages/core/src/__tests__/core/legacy-entrypoint.functional.test.ts legacy wrapper runtime barrel guardrail follow-up`
 - [ ] `packages/web-server/src/services/config-management.service.ts web server config lifecycle boundary follow-up`
 - [ ] `packages/web-server/src/services/file-watcher.service.ts web server analytics watcher runtime boundary follow-up`
 - [ ] `packages/web-server/src/middleware/request-logging.middleware.ts web server runtime logging boundary follow-up`
+- [ ] `packages/web-server/tests/request-logging.middleware.test.ts web server runtime logging guardrail follow-up`
 - [ ] `packages/web-server/src/middleware/error-handler.middleware.ts web server structured error middleware boundary follow-up`
+- [ ] `packages/web-server/tests/error-handler.middleware.test.ts web server structured error middleware guardrail follow-up`
 - [ ] `packages/web-server/src/errors/api-error-response.ts web server structured error contract boundary follow-up`
+- [ ] `packages/web-server/tests/api-error-response.test.ts web server structured error contract guardrail follow-up`
 - [ ] `packages/web-server/src/logging/request-scoped-error-log.ts web server request-scoped logging contract boundary follow-up`
+- [ ] `packages/core/src/__tests__/web/web-boundary.test.ts web server adapter contract guardrail follow-up`
+- [ ] `packages/core/src/__tests__/core/readme-entrypoint-boundary.functional.test.ts runtime handoff docs guardrail follow-up`
+- [ ] `packages/core/src/__tests__/core/architecture-entrypoint-boundary.functional.test.ts runtime handoff docs guardrail follow-up`
+- [ ] `packages/core/src/__tests__/core/legacy-entrypoint.functional.test.ts legacy wrapper runtime barrel guardrail follow-up`
 
 ## Completed History
+- [x] `packages/web-server/src/routes/analytics.routes.ts analytics route runtime adapter boundary follow-up` | prod: yes | tests: yes | func: yes
+- [x] `packages/web-server/src/routes/route-response.ts web server shared route response runtime boundary follow-up` | prod: yes | tests: yes | func: yes
+- [x] `packages/web-server/src/routes/analytics.constants.ts analytics route runtime constants boundary follow-up` | prod: yes | tests: yes | func: yes
 - [x] `packages/web-server/tests/web-server.functional.test.ts web server route adapter composition guardrail follow-up` | prod: yes | tests: yes | func: yes
 - [x] `packages/web-server/src/websocket/ws-server.ts websocket bridge runtime adapter boundary follow-up` | prod: yes | tests: yes | func: yes
 - [x] `packages/web-server/tests/ws-server.functional.test.ts websocket bridge runtime adapter functional guardrail follow-up` | prod: yes | tests: yes | func: yes

packages/web-server/src/routes/analytics.constants.ts

@@ -1 +1,16 @@
 export const DEFAULT_EQUITY_CURVE_STARTING_BALANCE = 1000;
+export const DEFAULT_ANALYTICS_JOURNAL_PAGE = 1;
+export const DEFAULT_ANALYTICS_JOURNAL_LIMIT = 50;
+export const MAX_ANALYTICS_JOURNAL_LIMIT = 500;
+export const DEFAULT_ANALYTICS_RECENT_JOURNAL_HOURS = 24;
+
+export const ANALYTICS_ROUTE_FALLBACK_MESSAGES = {
+  journal: 'Failed to fetch journal',
+  recentJournal: 'Failed to fetch recent journal',
+  journalStats: 'Failed to fetch journal statistics',
+  sessions: 'Failed to fetch sessions',
+  compareSessions: 'Failed to compare sessions',
+  strategyPerformance: 'Failed to fetch strategy performance',
+  pnlHistory: 'Failed to fetch PnL history',
+  equityCurve: 'Failed to fetch equity curve',
+} as const;

packages/web-server/src/routes/analytics.routes.ts

@@ -25,14 +25,34 @@ import {
   requireNonEmptyParam,
   sendAsyncRouteRead,
 } from './route-response.js';
-import { DEFAULT_EQUITY_CURVE_STARTING_BALANCE } from './analytics.constants.js';
+import {
+  ANALYTICS_ROUTE_FALLBACK_MESSAGES,
+  DEFAULT_ANALYTICS_JOURNAL_LIMIT,
+  DEFAULT_ANALYTICS_JOURNAL_PAGE,
+  DEFAULT_ANALYTICS_RECENT_JOURNAL_HOURS,
+  DEFAULT_EQUITY_CURVE_STARTING_BALANCE,
+  MAX_ANALYTICS_JOURNAL_LIMIT,
+} from './analytics.constants.js';
 
 type AnalyticsRouteDerivedReadApi = {
   getPnlHistory(): Promise<PnlHistoryPoint[]>;
   getEquityCurve(): Promise<EquityCurvePoint[]>;
 };
 
-export type AnalyticsRouteReadApi = FileWatcherAnalyticsReadApi & AnalyticsRouteDerivedReadApi;
+type AnalyticsRouteJournalReadApi = Pick<
+  FileWatcherAnalyticsReadApi,
+  'getJournalPaginated' | 'getJournalFromLastHours' | 'getJournalStats' | 'readJournal'
+>;
+type AnalyticsRouteSessionReadApi = Pick<FileWatcherAnalyticsReadApi, 'readSessions' | 'compareSessions'>;
+type AnalyticsRouteStrategyReadApi = Pick<FileWatcherAnalyticsReadApi, 'getStrategyPerformance'>;
+type AnalyticsRouteCurveReadApi = AnalyticsRouteDerivedReadApi;
+
+export type AnalyticsRouteReadApi = {
+  journal: AnalyticsRouteJournalReadApi;
+  sessions: AnalyticsRouteSessionReadApi;
+  strategy: AnalyticsRouteStrategyReadApi;
+  curves: AnalyticsRouteCurveReadApi;
+};
 type SessionComparisonRouteQuery = { id1: string; id2: string };
 
 function createPnlHistory(journal: WebApiJournalEntry[]): PnlHistoryPoint[] {
@@ -68,17 +88,27 @@ function createEquityCurve(journal: WebApiJournalEntry[]): EquityCurvePoint[] {
 }
 
 export function createAnalyticsRouteReadApi(readApi: FileWatcherAnalyticsReadApi): AnalyticsRouteReadApi {
-  return {
-    getJournalPaginated: (page, limit) => readApi.getJournalPaginated(page, limit),
-    getJournalFromLastHours: (hours) => readApi.getJournalFromLastHours(hours),
+  const journal = {
+    getJournalPaginated: (page: number | undefined, limit: number | undefined) => readApi.getJournalPaginated(page, limit),
+    getJournalFromLastHours: (hours: number | undefined) => readApi.getJournalFromLastHours(hours),
     getJournalStats: () => readApi.getJournalStats(),
-    readSessions: () => readApi.readSessions(),
-    compareSessions: (id1, id2) => readApi.compareSessions(id1, id2),
-    getStrategyPerformance: () => readApi.getStrategyPerformance(),
-    getPnlHistory: async () => createPnlHistory(await readApi.readJournal()),
-    getEquityCurve: async () => createEquityCurve(await readApi.readJournal()),
     readJournal: () => readApi.readJournal(),
   };
+
+  return {
+    journal,
+    sessions: {
+      readSessions: () => readApi.readSessions(),
+      compareSessions: (id1, id2) => readApi.compareSessions(id1, id2),
+    },
+    strategy: {
+      getStrategyPerformance: () => readApi.getStrategyPerformance(),
+    },
+    curves: {
+      getPnlHistory: async () => createPnlHistory(await journal.readJournal()),
+      getEquityCurve: async () => createEquityCurve(await journal.readJournal()),
+    },
+  };
 }
 
 function requireSessionComparisonQuery(
@@ -95,7 +125,7 @@ function requireSessionComparisonQuery(
   return { id1, id2 };
 }
 
-export function createAnalyticsRoutes(fileWatcher: AnalyticsRouteReadApi): Router {
+export function createAnalyticsRoutes(analyticsApi: AnalyticsRouteReadApi): Router {
   const router = Router();
 
   /**
@@ -104,36 +134,36 @@ export function createAnalyticsRoutes(fileWatcher: AnalyticsRouteReadApi): Route
    */
   router.get('/journal', async (req: Request, res: Response<ApiResponse<JournalPagePayload>>) =>
     sendAsyncRouteRead(res, async () => {
-      const page = parsePageQuery(req.query.page);
-      const limit = parseLimitQuery(req.query.limit, 50, 500);
-      return fileWatcher.getJournalPaginated(page, limit);
-    }, { fallbackMessage: 'Failed to fetch journal' }));
+      const page = parsePageQuery(req.query.page, DEFAULT_ANALYTICS_JOURNAL_PAGE);
+      const limit = parseLimitQuery(req.query.limit, DEFAULT_ANALYTICS_JOURNAL_LIMIT, MAX_ANALYTICS_JOURNAL_LIMIT);
+      return analyticsApi.journal.getJournalPaginated(page, limit);
+    }, { fallbackMessage: ANALYTICS_ROUTE_FALLBACK_MESSAGES.journal }));
 
   /**
    * GET /api/analytics/journal/last24h
    * Get trades from last 24 hours
    */
   router.get('/journal/last24h', async (_req: Request, res: Response<ApiResponse<WebApiJournalEntry[]>>) =>
-    sendAsyncRouteRead(res, () => fileWatcher.getJournalFromLastHours(24), {
-      fallbackMessage: 'Failed to fetch recent journal',
+    sendAsyncRouteRead(res, () => analyticsApi.journal.getJournalFromLastHours(DEFAULT_ANALYTICS_RECENT_JOURNAL_HOURS), {
+      fallbackMessage: ANALYTICS_ROUTE_FALLBACK_MESSAGES.recentJournal,
     }));
 
   /**
    * GET /api/analytics/journal/stats
    * Get overall journal statistics
    */
   router.get('/journal/stats', async (_req: Request, res: Response<ApiResponse<JournalStatsPayload>>) =>
-    sendAsyncRouteRead(res, () => fileWatcher.getJournalStats(), {
-      fallbackMessage: 'Failed to fetch journal statistics',
+    sendAsyncRouteRead(res, () => analyticsApi.journal.getJournalStats(), {
+      fallbackMessage: ANALYTICS_ROUTE_FALLBACK_MESSAGES.journalStats,
     }));
 
   /**
    * GET /api/analytics/sessions
    * Get all sessions
    */
   router.get('/sessions', async (_req: Request, res: Response<ApiResponse<WebApiSessionStats[]>>) =>
-    sendAsyncRouteRead(res, () => fileWatcher.readSessions(), {
-      fallbackMessage: 'Failed to fetch sessions',
+    sendAsyncRouteRead(res, () => analyticsApi.sessions.readSessions(), {
+      fallbackMessage: ANALYTICS_ROUTE_FALLBACK_MESSAGES.sessions,
     }));
 
   /**
@@ -146,8 +176,8 @@ export function createAnalyticsRoutes(fileWatcher: AnalyticsRouteReadApi): Route
       return;
     }
 
-    await sendAsyncRouteRead(res, () => fileWatcher.compareSessions(comparisonQuery.id1, comparisonQuery.id2), {
-      fallbackMessage: 'Failed to compare sessions',
+    await sendAsyncRouteRead(res, () => analyticsApi.sessions.compareSessions(comparisonQuery.id1, comparisonQuery.id2), {
+      fallbackMessage: ANALYTICS_ROUTE_FALLBACK_MESSAGES.compareSessions,
     });
   });
 
@@ -156,23 +186,27 @@ export function createAnalyticsRoutes(fileWatcher: AnalyticsRouteReadApi): Route
    * Get performance breakdown by strategy
    */
   router.get('/strategy-performance', async (_req: Request, res: Response<ApiResponse<StrategyPerformancePayload[]>>) =>
-    sendAsyncRouteRead(res, () => fileWatcher.getStrategyPerformance(), {
-      fallbackMessage: 'Failed to fetch strategy performance',
+    sendAsyncRouteRead(res, () => analyticsApi.strategy.getStrategyPerformance(), {
+      fallbackMessage: ANALYTICS_ROUTE_FALLBACK_MESSAGES.strategyPerformance,
     }));
 
   /**
    * GET /api/analytics/pnl-history
    * Get PnL over time for charting
    */
   router.get('/pnl-history', async (_req: Request, res: Response<ApiResponse<PnlHistoryPoint[]>>) =>
-    sendAsyncRouteRead(res, () => fileWatcher.getPnlHistory(), { fallbackMessage: 'Failed to fetch PnL history' }));
+    sendAsyncRouteRead(res, () => analyticsApi.curves.getPnlHistory(), {
+      fallbackMessage: ANALYTICS_ROUTE_FALLBACK_MESSAGES.pnlHistory,
+    }));
 
   /**
    * GET /api/analytics/equity-curve
    * Get equity curve data (cumulative balance over time)
    */
   router.get('/equity-curve', async (_req: Request, res: Response<ApiResponse<EquityCurvePoint[]>>) =>
-    sendAsyncRouteRead(res, () => fileWatcher.getEquityCurve(), { fallbackMessage: 'Failed to fetch equity curve' }));
+    sendAsyncRouteRead(res, () => analyticsApi.curves.getEquityCurve(), {
+      fallbackMessage: ANALYTICS_ROUTE_FALLBACK_MESSAGES.equityCurve,
+    }));
 
   return router;
 }