refactor: complete v2 refactoring plan (Phases 1-5)

Phase 1 — Quick Wins: centralize formatMoney/formatCents, extract
findUniqueOrThrow helper (19 routers), shared Prisma select constants,
useInvalidatePlanningViews hook, status badge consolidation, composite
DB indexes.

Phase 2 — Timeline Split: extract TimelineContext, TimelineResourcePanel,
TimelineProjectPanel; split 28-dep useMemo into 3 focused memos.
TimelineView.tsx reduced from 1,903 to 538 lines.

Phase 3 — Query Performance: server-side filtering for getEntriesView,
remove availability from timeline resource select, SSE event debouncing
(50ms batch window).

Phase 4 — Estimate Workspace: extract 7 tab components and 3 editor
components. EstimateWorkspaceClient 1,298→306 lines,
EstimateWorkspaceDraftEditor 1,205→581 lines.

Phase 5 — Package Cleanup: split commit-dispo-import-batch (1,112→573
lines), extract shared pagination helper with 11 tests.

All tests pass: 209 API, 254 engine, 67 application.

Co-Authored-By: claude-flow <ruv@ruv.net>

packages/api/src/db/helpers.ts

@@ -0,0 +1,12 @@
+import { TRPCError } from "@trpc/server";
+
+export async function findUniqueOrThrow<T>(
+  query: Promise<T | null>,
+  entityName: string,
+): Promise<T> {
+  const result = await query;
+  if (!result) {
+    throw new TRPCError({ code: "NOT_FOUND", message: `${entityName} not found` });
+  }
+  return result;
+}

packages/api/src/db/pagination.ts

@@ -0,0 +1,100 @@
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Input schema — merge into any tRPC procedure input with `.merge()` or spread
+// ---------------------------------------------------------------------------
+
+export const PaginationInputSchema = z.object({
+  page: z.number().int().min(1).default(1),
+  limit: z.number().int().min(1).max(500).default(50),
+  cursor: z.string().optional(),
+});
+
+export type PaginationInput = z.infer<typeof PaginationInputSchema>;
+
+// ---------------------------------------------------------------------------
+// Result envelope
+// ---------------------------------------------------------------------------
+
+export interface PaginatedResult<T> {
+  items: T[];
+  total: number;
+  page: number;
+  limit: number;
+  nextCursor: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Core paginate helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a Prisma-style `findMany` + `count` with the project's standard
+ * offset+cursor hybrid pagination and the `take: limit + 1` sentinel trick.
+ *
+ * @param findMany  Prisma `findMany` (or compatible) that receives `{ skip, take }`.
+ *                  The caller is responsible for applying `where`/`orderBy`/`include`
+ *                  and for injecting the cursor condition into `where` when
+ *                  `cursorWhere` is provided.
+ * @param count     Prisma `count` for the *base* where clause (without cursor).
+ * @param input     The validated pagination input fields.
+ * @param getId     Optional — extract the cursor id from the last item.
+ *                  Defaults to `item.id` for items that have an `id: string`.
+ */
+export async function paginate<T>(
+  findMany: (args: { skip: number; take: number }) => Promise<T[]>,
+  count: () => Promise<number>,
+  input: PaginationInput,
+  getId: (item: T) => string = (item) => (item as unknown as { id: string }).id,
+): Promise<PaginatedResult<T>> {
+  const page = input.page ?? 1;
+  const limit = input.limit ?? 50;
+  const skip = input.cursor ? 0 : (page - 1) * limit;
+
+  const [rawItems, total] = await Promise.all([
+    findMany({ skip, take: limit + 1 }),
+    count(),
+  ]);
+
+  const hasMore = rawItems.length > limit;
+  const items = hasMore ? rawItems.slice(0, limit) : rawItems;
+  const nextCursor = hasMore && items.length > 0 ? getId(items[items.length - 1]!) : null;
+
+  return { items, total, page, limit, nextCursor };
+}
+
+// ---------------------------------------------------------------------------
+// Cursor-only variant (no total count, lighter)
+// ---------------------------------------------------------------------------
+
+export interface CursorResult<T> {
+  items: T[];
+  nextCursor: string | null;
+}
+
+export const CursorInputSchema = z.object({
+  limit: z.number().int().min(1).max(500).default(50),
+  cursor: z.string().optional(),
+});
+
+export type CursorInput = z.infer<typeof CursorInputSchema>;
+
+/**
+ * Cursor-only pagination without a total count query.
+ * Useful for large tables or infinite-scroll UIs that don't need a total.
+ */
+export async function paginateCursor<T>(
+  findMany: (args: { take: number }) => Promise<T[]>,
+  input: CursorInput,
+  getId: (item: T) => string = (item) => (item as unknown as { id: string }).id,
+): Promise<CursorResult<T>> {
+  const limit = input.limit ?? 50;
+
+  const rawItems = await findMany({ take: limit + 1 });
+
+  const hasMore = rawItems.length > limit;
+  const items = hasMore ? rawItems.slice(0, limit) : rawItems;
+  const nextCursor = hasMore && items.length > 0 ? getId(items[items.length - 1]!) : null;
+
+  return { items, nextCursor };
+}

packages/api/src/db/selects.ts

@@ -0,0 +1,3 @@
+export const ROLE_BRIEF_SELECT = { id: true, name: true, color: true } as const;
+export const PROJECT_BRIEF_SELECT = { id: true, name: true, shortCode: true, status: true, endDate: true } as const;
+export const RESOURCE_BRIEF_SELECT = { id: true, displayName: true, eid: true, lcrCents: true } as const;