@hed-hog/operations 0.0.294 → 0.0.296

package/src/operations.service.ts

@@ -1,137 +1,3595 @@
-import { Injectable } from '@nestjs/common';
-
-const operationalCollections = {
-  contracts: [
-    { id: 1, code: 'CTR-001', name: 'Northwind Retainer', status: 'active' },
-    { id: 2, code: 'CTR-002', name: 'BluePeak Migration', status: 'renewal' },
-  ],
-  projects: [
-    { id: 1, code: 'PRJ-OPS-1', name: 'Phoenix Platform Rollout', status: 'active' },
-    { id: 2, code: 'PRJ-OPS-2', name: 'Northwind Service Desk', status: 'at_risk' },
-  ],
-  allocations: [
-    { id: 1, employeeId: 1, projectId: 1, weeklyHours: 30, allocationPercent: 75 },
-    { id: 2, employeeId: 2, projectId: 2, weeklyHours: 20, allocationPercent: 50 },
-  ],
-  tasks: [
-    { id: 1, title: 'Deploy onboarding workflow', status: 'review' },
-    { id: 2, title: 'Refine support KPI dashboard', status: 'in_progress' },
-  ],
-  timesheets: [
-    { id: 1, employeeId: 1, status: 'submitted', cycleStartDate: '2026-03-09' },
-    { id: 2, employeeId: 2, status: 'approved', cycleStartDate: '2026-03-09' },
-  ],
-  approvals: [
-    { id: 1, employeeId: 1, status: 'pending', hours: 8 },
-    { id: 2, employeeId: 3, status: 'pending', hours: 6.5 },
-  ],
-};
-
-const growthCollections = {
-  growth: {
-    topSignals: ['score_events', 'career_tracks', 'goals', 'recognitions'],
-    note: 'Foundation endpoint for the employee growth dashboard.',
-  },
-  evaluations: [
-    { id: 1, employeeId: 1, cycle: '2026 H1 Growth Cycle', status: 'finalized', generatedScore: 84 },
-    { id: 2, employeeId: 2, cycle: '2026 Delivery Sprint Review', status: 'submitted', generatedScore: 72 },
-  ],
-  goals: [
-    { id: 1, employeeId: 1, title: 'Reduce rework under 5%', status: 'active', progressPercent: 68 },
-    { id: 2, employeeId: 2, title: 'Close Scrum certification', status: 'at_risk', progressPercent: 35 },
-  ],
-  certifications: [
-    { id: 1, slug: 'scrum-master-foundations', status: 'achieved' },
-    { id: 2, slug: 'advanced-quality-assurance', status: 'planned' },
-  ],
-  rewards: [
-    { id: 1, employeeId: 1, rewardType: 'bonus', status: 'granted' },
-    { id: 2, employeeId: 3, rewardType: 'recognition', status: 'granted' },
-  ],
-  career: [
-    { id: 1, track: 'Delivery', currentLevel: 'Consultant', nextLevel: 'Senior Consultant' },
-    { id: 2, track: 'Specialist', currentLevel: 'Specialist II', nextLevel: 'Principal Specialist' },
-  ],
-  manager: {
-    summary: {
-      promotionEligible: 2,
-      goalsAtRisk: 3,
-      pendingCertifications: 4,
-    },
-  },
-};
-
-@Injectable()
-export class OperationsService {
-  // TODO: Replace static collections with Prisma queries after the first schema apply.
-  // TODO: Promotion must not be derived from score alone; score remains only a support signal.
-  // TODO: Certifications are supporting evidence and do not guarantee promotion on their own.
-  // TODO: Future readiness logic must consider individual, team, and org impact, plus time operating at the next level and calibration outcomes.
-  getDashboard() {
-    return {
-      module: 'operations',
-      operationalCollections,
-      growthCollections,
-    };
-  }
-
-  listContracts() {
-    return operationalCollections.contracts;
-  }
-
-  getContractById(id: number) {
-    return operationalCollections.contracts.find((item) => item.id === id) ?? null;
-  }
-
-  listProjects() {
-    return operationalCollections.projects;
-  }
-
-  getProjectById(id: number) {
-    return operationalCollections.projects.find((item) => item.id === id) ?? null;
-  }
-
-  listAllocations() {
-    return operationalCollections.allocations;
-  }
-
-  listTasks() {
-    return operationalCollections.tasks;
-  }
-
-  listTimesheets() {
-    return operationalCollections.timesheets;
-  }
-
-  listApprovals() {
-    return operationalCollections.approvals;
-  }
-
-  getGrowthDashboard() {
-    return growthCollections.growth;
-  }
-
-  listEvaluations() {
-    return growthCollections.evaluations;
-  }
-
-  listGoals() {
-    return growthCollections.goals;
-  }
-
-  listCertifications() {
-    return growthCollections.certifications;
-  }
-
-  listRewards() {
-    return growthCollections.rewards;
-  }
-
-  listCareerPaths() {
-    return growthCollections.career;
-  }
-
-  getManagerOverview() {
-    return growthCollections.manager;
-  }
-}
+import { PrismaService } from '@hed-hog/api-prisma';
+import { IntegrationDeveloperApiService } from '@hed-hog/core';
+import {
+    BadRequestException,
+    ForbiddenException,
+    Injectable,
+    NotFoundException,
+} from '@nestjs/common';
+
+const COLLABORATOR_ROLE = 'admin-operations-collaborator';
+const SUPERVISOR_ROLE = 'admin-operations-supervisor';
+const DIRECTOR_ROLE = 'admin-operations-director';
+
+type ApprovalAction = 'approve' | 'reject';
+type ApprovalTargetType =
+  | 'timesheet'
+  | 'time_off_request'
+  | 'schedule_adjustment_request';
+
+type ActorContext = {
+  userId: number;
+  roleSlugs: string[];
+  collaboratorId: number | null;
+  collaboratorName: string | null;
+  isDirector: boolean;
+  isSupervisor: boolean;
+  isCollaborator: boolean;
+  teamCollaboratorIds: number[];
+  visibleCollaboratorIds: number[];
+  visibleProjectIds: number[];
+};
+
+type CollaboratorPayload = {
+  userId: number;
+  code: string;
+  displayName: string;
+  collaboratorType?: 'clt' | 'pj' | 'freelancer' | 'intern' | 'other';
+  department?: string | null;
+  title?: string | null;
+  levelLabel?: string | null;
+  supervisorCollaboratorId?: number | null;
+  weeklyCapacityHours?: number | null;
+  status?: 'active' | 'on_leave' | 'inactive';
+  joinedAt?: string | null;
+  leftAt?: string | null;
+  compensationAmount?: number | null;
+  contractDescription?: string | null;
+  autoGenerateContractDraft?: boolean;
+  weeklySchedule?: Array<{
+    weekday:
+      | 'monday'
+      | 'tuesday'
+      | 'wednesday'
+      | 'thursday'
+      | 'friday'
+      | 'saturday'
+      | 'sunday';
+    isWorkingDay?: boolean;
+    startTime?: string | null;
+    endTime?: string | null;
+    breakMinutes?: number | null;
+  }>;
+  notes?: string | null;
+};
+
+type ContractPayload = {
+  code: string;
+  name: string;
+  clientName: string;
+  contractCategory?:
+    | 'employee'
+    | 'contractor'
+    | 'client'
+    | 'supplier'
+    | 'vendor'
+    | 'partner'
+    | 'internal'
+    | 'other';
+  contractType?:
+    | 'clt'
+    | 'pj'
+    | 'freelancer_agreement'
+    | 'service_agreement'
+    | 'fixed_term'
+    | 'recurring_service'
+    | 'nda'
+    | 'amendment'
+    | 'addendum'
+    | 'other';
+  billingModel?:
+    | 'time_and_material'
+    | 'monthly_retainer'
+    | 'fixed_price';
+  signatureStatus?:
+    | 'not_started'
+    | 'pending'
+    | 'partially_signed'
+    | 'signed'
+    | 'expired';
+  isActive?: boolean;
+  accountManagerCollaboratorId?: number | null;
+  relatedCollaboratorId?: number | null;
+  originType?: 'manual' | 'employee_hiring' | 'client_project';
+  originId?: number | null;
+  startDate: string;
+  endDate?: string | null;
+  signedAt?: string | null;
+  effectiveDate?: string | null;
+  budgetAmount?: number | null;
+  monthlyHourCap?: number | null;
+  status?:
+    | 'draft'
+    | 'under_review'
+    | 'active'
+    | 'renewal'
+    | 'expired'
+    | 'closed'
+    | 'archived';
+  description?: string | null;
+  contentHtml?: string | null;
+  parties?: Array<{
+    partyRole?:
+      | 'employee'
+      | 'employer'
+      | 'client'
+      | 'supplier'
+      | 'vendor'
+      | 'partner'
+      | 'witness'
+      | 'internal_owner'
+      | 'other';
+    partyType?: 'individual' | 'company' | 'internal_team' | 'other';
+    displayName: string;
+    documentNumber?: string | null;
+    email?: string | null;
+    phone?: string | null;
+    isPrimary?: boolean;
+  }>;
+  signatures?: Array<{
+    signerName: string;
+    signerRole?: string | null;
+    signerEmail?: string | null;
+    status?: 'pending' | 'signed' | 'rejected';
+    signedAt?: string | null;
+  }>;
+  financialTerms?: Array<{
+    termType?: 'value' | 'payment' | 'revenue' | 'fine' | 'other';
+    label: string;
+    amount: number;
+    recurrence?: 'one_time' | 'monthly' | 'quarterly' | 'yearly' | 'other';
+    dueDay?: number | null;
+    notes?: string | null;
+  }>;
+  revisions?: Array<{
+    revisionType?: 'amendment' | 'renewal' | 'revision' | 'addendum' | 'other';
+    title: string;
+    effectiveDate?: string | null;
+    status?: 'draft' | 'active' | 'completed' | 'cancelled';
+    summary?: string | null;
+  }>;
+  replaceUploadedPdfDocument?: {
+    fileName: string;
+    mimeType: string;
+    fileContentBase64: string;
+    notes?: string | null;
+  } | null;
+};
+
+type ProjectPayload = {
+  contractId?: number | null;
+  managerCollaboratorId?: number | null;
+  code: string;
+  name: string;
+  clientName?: string | null;
+  summary?: string | null;
+  status?:
+    | 'planning'
+    | 'active'
+    | 'at_risk'
+    | 'paused'
+    | 'completed'
+    | 'archived';
+  progressPercent?: number | null;
+  deliveryModel?:
+    | 'dedicated_team'
+    | 'shared_team'
+    | 'project_delivery'
+    | 'support';
+  budgetAmount?: number | null;
+  startDate?: string | null;
+  endDate?: string | null;
+  billingModel?:
+    | 'time_and_material'
+    | 'monthly_retainer'
+    | 'fixed_price';
+  monthlyHourCap?: number | null;
+  contractCode?: string | null;
+  contractName?: string | null;
+  contractDescription?: string | null;
+  autoGenerateContractDraft?: boolean;
+  teamAssignments?: Array<{
+    collaboratorId: number;
+    roleLabel?: string | null;
+    allocationPercent?: number | null;
+    weeklyHours?: number | null;
+    isBillable?: boolean;
+    startDate?: string | null;
+    endDate?: string | null;
+    status?: 'planned' | 'active' | 'completed' | 'cancelled';
+  }>;
+};
+
+type TimesheetEntryPayload = {
+  projectAssignmentId?: number | null;
+  activityLabel?: string | null;
+  workDate: string;
+  hours: number;
+  description?: string | null;
+};
+
+type TimesheetPayload = {
+  collaboratorId?: number | null;
+  weekStartDate: string;
+  weekEndDate: string;
+  notes?: string | null;
+  entries?: TimesheetEntryPayload[];
+};
+
+type TimeOffPayload = {
+  collaboratorId?: number | null;
+  requestType?:
+    | 'vacation'
+    | 'personal_time'
+    | 'sick_leave'
+    | 'unpaid_leave'
+    | 'other';
+  startDate: string;
+  endDate: string;
+  totalDays?: number | null;
+  reason?: string | null;
+};
+
+type ScheduleAdjustmentDayPayload = {
+  weekday:
+    | 'monday'
+    | 'tuesday'
+    | 'wednesday'
+    | 'thursday'
+    | 'friday'
+    | 'saturday'
+    | 'sunday';
+  isWorkingDay?: boolean;
+  startTime?: string | null;
+  endTime?: string | null;
+  breakMinutes?: number | null;
+};
+
+type ScheduleAdjustmentPayload = {
+  collaboratorId?: number | null;
+  requestScope?: 'temporary' | 'permanent';
+  effectiveStartDate: string;
+  effectiveEndDate?: string | null;
+  reason?: string | null;
+  days: ScheduleAdjustmentDayPayload[];
+};
+
+type DecisionPayload = {
+  note?: string | null;
+};
+
+type PublishAccountsPayableReferencePayload = {
+  sourceEntityId: string;
+  sourceEntityType?: string;
+  personId: number;
+  dueDate: string;
+  totalAmount: number;
+  documentNumber: string;
+  description?: string | null;
+  paymentChannel?: string | null;
+  financeCategoryId?: number | null;
+  costCenterId?: number | null;
+  locale?: string;
+};
+
+@Injectable()
+export class OperationsService {
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly integrationApi: IntegrationDeveloperApiService,
+  ) {}
+
+  async getDashboard(userId: number) {
+    const actor = await this.getActorContext(userId);
+    const projectFilter = this.buildIdFilter(
+      actor.visibleProjectIds,
+      'p.id',
+      actor.isDirector
+    );
+    const collaboratorFilter = this.buildIdFilter(
+      actor.visibleCollaboratorIds,
+      't.collaborator_id',
+      actor.isDirector
+    );
+    const timeOffFilter = this.buildIdFilter(
+      actor.visibleCollaboratorIds,
+      'tor.collaborator_id',
+      actor.isDirector
+    );
+    const scheduleFilter = this.buildIdFilter(
+      actor.visibleCollaboratorIds,
+      'sar.collaborator_id',
+      actor.isDirector
+    );
+    const approvalFilter = actor.isDirector
+      ? { clause: 'a.deleted_at IS NULL', params: [] as unknown[] }
+      : actor.collaboratorId
+        ? {
+            clause:
+              'a.deleted_at IS NULL AND a.approver_collaborator_id = $1',
+            params: [actor.collaboratorId] as unknown[],
+          }
+        : { clause: '1 = 0', params: [] as unknown[] };
+
+    const [projects, timesheets, timeOff, schedules, approvals, recentTimesheets] =
+      await Promise.all([
+        this.querySingle<{ total: string; active: string }>(
+          `SELECT COUNT(*)::text AS total,
+                  COUNT(*) FILTER (WHERE status = 'active')::text AS active
+             FROM operations_project p
+            WHERE p.deleted_at IS NULL AND ${projectFilter.clause}`,
+          projectFilter.params
+        ),
+        this.querySingle<{ total: string; submitted: string }>(
+          `SELECT COUNT(*)::text AS total,
+                  COUNT(*) FILTER (WHERE status = 'submitted')::text AS submitted
+             FROM operations_timesheet t
+            WHERE t.deleted_at IS NULL AND ${collaboratorFilter.clause}`,
+          collaboratorFilter.params
+        ),
+        this.querySingle<{ total: string; submitted: string }>(
+          `SELECT COUNT(*)::text AS total,
+                  COUNT(*) FILTER (WHERE status = 'submitted')::text AS submitted
+             FROM operations_time_off_request tor
+            WHERE tor.deleted_at IS NULL AND ${timeOffFilter.clause}`,
+          timeOffFilter.params
+        ),
+        this.querySingle<{ total: string; submitted: string }>(
+          `SELECT COUNT(*)::text AS total,
+                  COUNT(*) FILTER (WHERE status = 'submitted')::text AS submitted
+             FROM operations_schedule_adjustment_request sar
+            WHERE sar.deleted_at IS NULL AND ${scheduleFilter.clause}`,
+          scheduleFilter.params
+        ),
+        this.querySingle<{ pending: string }>(
+          `SELECT COUNT(*) FILTER (WHERE status = 'pending')::text AS pending
+             FROM operations_approval a
+            WHERE ${approvalFilter.clause}`,
+          approvalFilter.params
+        ),
+        this.queryRows<{
+          id: number;
+          collaboratorName: string;
+          weekStartDate: string;
+          weekEndDate: string;
+          totalHours: number | null;
+          status: string;
+        }>(
+          `SELECT t.id,
+                  c.display_name AS "collaboratorName",
+                  t.week_start_date AS "weekStartDate",
+                  t.week_end_date AS "weekEndDate",
+                  t.total_hours AS "totalHours",
+                  t.status
+             FROM operations_timesheet t
+             JOIN operations_collaborator c ON c.id = t.collaborator_id
+            WHERE t.deleted_at IS NULL AND ${collaboratorFilter.clause}
+            ORDER BY COALESCE(t.submitted_at, t.updated_at) DESC
+            LIMIT 5`,
+          collaboratorFilter.params
+        ),
+      ]);
+
+    return {
+      actor: {
+        roleScope: actor.isDirector
+          ? 'full'
+          : actor.isSupervisor
+            ? 'team'
+            : 'self',
+        collaboratorId: actor.collaboratorId,
+        collaboratorName: actor.collaboratorName,
+        teamSize: actor.teamCollaboratorIds.length,
+      },
+      cards: {
+        projectsTotal: Number(projects?.total ?? 0),
+        activeProjects: Number(projects?.active ?? 0),
+        visibleTimesheets: Number(timesheets?.total ?? 0),
+        pendingTimesheets: Number(timesheets?.submitted ?? 0),
+        timeOffRequests: Number(timeOff?.total ?? 0),
+        scheduleAdjustmentRequests: Number(schedules?.total ?? 0),
+        pendingApprovals: Number(approvals?.pending ?? 0),
+      },
+      recentTimesheets,
+    };
+  }
+
+  async listCollaborators(userId: number) {
+    const actor = await this.getActorContext(userId);
+    this.ensureCollaborator(actor);
+    const filter = this.buildIdFilter(
+      actor.visibleCollaboratorIds,
+      'c.id',
+      actor.isDirector
+    );
+
+    return this.queryRows(
+      `SELECT c.id,
+              c.user_id AS "userId",
+              c.code,
+              c.collaborator_type AS "collaboratorType",
+              c.display_name AS "displayName",
+              c.department,
+              c.title,
+              c.level_label AS "levelLabel",
+              c.weekly_capacity_hours AS "weeklyCapacityHours",
+              c.status,
+              c.joined_at AS "joinedAt",
+              c.left_at AS "leftAt",
+              c.notes,
+              s.id AS "supervisorId",
+              s.display_name AS "supervisorName",
+              hiring_contract.id AS "contractId",
+              hiring_contract.status AS "contractStatus",
+              COUNT(DISTINCT pa.id)::int AS "activeAssignments"
+         FROM operations_collaborator c
+         LEFT JOIN operations_collaborator s
+           ON s.id = c.supervisor_collaborator_id
+         LEFT JOIN operations_project_assignment pa
+           ON pa.collaborator_id = c.id
+          AND pa.deleted_at IS NULL
+          AND pa.status IN ('planned', 'active')
+         LEFT JOIN LATERAL (
+           SELECT oc.id, oc.status
+             FROM operations_contract oc
+            WHERE oc.related_collaborator_id = c.id
+              AND oc.deleted_at IS NULL
+            ORDER BY CASE WHEN oc.origin_type = 'employee_hiring' THEN 0 ELSE 1 END,
+                     oc.created_at DESC
+            LIMIT 1
+         ) hiring_contract ON TRUE
+        WHERE c.deleted_at IS NULL
+          AND ${filter.clause}
+        GROUP BY c.id, s.id, hiring_contract.id, hiring_contract.status
+        ORDER BY c.display_name ASC`,
+      filter.params
+    );
+  }
+
+  async getMyCollaborator(userId: number) {
+    const actor = await this.getActorContext(userId);
+    if (!actor.collaboratorId) {
+      throw new NotFoundException('No collaborator profile linked to this user.');
+    }
+    return this.getCollaboratorByIdForUser(userId, actor.collaboratorId);
+  }
+
+  async getCollaboratorByIdForUser(userId: number, collaboratorId: number) {
+    const actor = await this.getActorContext(userId);
+    this.ensureCollaboratorAccess(actor, collaboratorId);
+    return this.getCollaboratorDetails(collaboratorId);
+  }
+
+  async getTeam(userId: number) {
+    const actor = await this.getActorContext(userId);
+    this.ensureSupervisor(actor);
+    if (!actor.teamCollaboratorIds.length) {
+      return {
+        teamMembers: [],
+        projectCount: 0,
+        pendingApprovals: 0,
+        pendingItems: {
+          timesheets: 0,
+          timeOffRequests: 0,
+          scheduleAdjustmentRequests: 0,
+        },
+        teamProjects: [],
+        pendingApprovalQueue: [],
+        pendingTimeOffRequests: [],
+        pendingScheduleAdjustmentRequests: [],
+      };
+    }
+
+    const teamFilter = this.buildIdFilter(actor.teamCollaboratorIds, 'c.id', false);
+    const teamMembers = await this.queryRows(
+      `SELECT c.id,
+              c.user_id AS "userId",
+              c.code,
+              c.display_name AS "displayName",
+              c.collaborator_type AS "collaboratorType",
+              c.department,
+              c.title,
+              c.status,
+              COUNT(DISTINCT pa.id)::int AS "activeAssignments",
+              COUNT(DISTINCT a.id) FILTER (WHERE a.status = 'pending')::int AS "pendingApprovals",
+              COUNT(DISTINCT tor.id) FILTER (WHERE tor.status = 'submitted')::int AS "pendingTimeOffRequests",
+              COUNT(DISTINCT sar.id) FILTER (WHERE sar.status = 'submitted')::int AS "pendingScheduleAdjustmentRequests"
+         FROM operations_collaborator c
+         LEFT JOIN operations_project_assignment pa
+           ON pa.collaborator_id = c.id
+          AND pa.deleted_at IS NULL
+          AND pa.status IN ('planned', 'active')
+         LEFT JOIN operations_approval a
+           ON a.requester_collaborator_id = c.id
+          AND a.deleted_at IS NULL
+          AND a.status = 'pending'
+         LEFT JOIN operations_time_off_request tor
+           ON tor.collaborator_id = c.id
+          AND tor.deleted_at IS NULL
+          AND tor.status = 'submitted'
+         LEFT JOIN operations_schedule_adjustment_request sar
+           ON sar.collaborator_id = c.id
+          AND sar.deleted_at IS NULL
+          AND sar.status = 'submitted'
+        WHERE c.deleted_at IS NULL AND ${teamFilter.clause}
+        GROUP BY c.id
+        ORDER BY c.display_name ASC`,
+      teamFilter.params
+    );
+
+    const [teamProjects, pendingApprovalQueue, pendingTimeOffRequests, pendingScheduleAdjustmentRequests] =
+      await Promise.all([
+        this.queryRows(
+          `SELECT p.id,
+                  p.code,
+                  p.name,
+                  p.client_name AS "clientName",
+                  p.status,
+                  COUNT(DISTINCT pa.collaborator_id)::int AS "teamSize",
+                  COUNT(DISTINCT t.id) FILTER (WHERE t.status = 'submitted')::int AS "pendingTimesheets"
+             FROM operations_project p
+             JOIN operations_project_assignment pa
+               ON pa.project_id = p.id
+              AND pa.deleted_at IS NULL
+              AND pa.status IN ('planned', 'active')
+             LEFT JOIN operations_timesheet_entry te
+               ON te.project_assignment_id = pa.id
+              AND te.deleted_at IS NULL
+             LEFT JOIN operations_timesheet t
+               ON t.id = te.timesheet_id
+              AND t.deleted_at IS NULL
+            WHERE p.deleted_at IS NULL
+              AND pa.collaborator_id = ANY($1::int[])
+            GROUP BY p.id
+            ORDER BY p.name ASC`,
+          [actor.teamCollaboratorIds]
+        ),
+        this.queryRows(
+          `SELECT a.id,
+                  a.target_type AS "targetType",
+                  a.target_id AS "targetId",
+                  a.requester_collaborator_id AS "requesterCollaboratorId",
+                  requester.display_name AS "requesterName",
+                  a.approver_collaborator_id AS "approverCollaboratorId",
+                  approver.display_name AS "approverName",
+                  a.status,
+                  a.submitted_at AS "submittedAt",
+                  a.decided_at AS "decidedAt",
+                  a.decision_note AS "decisionNote",
+                  t.week_start_date AS "timesheetWeekStartDate",
+                  t.week_end_date AS "timesheetWeekEndDate",
+                  t.total_hours AS "timesheetTotalHours",
+                  COALESCE(
+                    STRING_AGG(DISTINCT p.name, ', ') FILTER (WHERE p.name IS NOT NULL),
+                    ''
+                  ) AS "timesheetProjectNames",
+                  tor.request_type AS "timeOffType",
+                  tor.start_date AS "timeOffStartDate",
+                  tor.end_date AS "timeOffEndDate",
+                  tor.reason AS "timeOffReason",
+                  sar.request_scope AS "scheduleRequestScope",
+                  sar.effective_start_date AS "scheduleStartDate",
+                  sar.effective_end_date AS "scheduleEndDate",
+                  sar.reason AS "scheduleReason"
+             FROM operations_approval a
+             JOIN operations_collaborator requester
+               ON requester.id = a.requester_collaborator_id
+             LEFT JOIN operations_collaborator approver
+               ON approver.id = a.approver_collaborator_id
+             LEFT JOIN operations_timesheet t
+               ON a.target_type = 'timesheet'
+              AND t.id = a.target_id
+             LEFT JOIN operations_timesheet_entry te
+               ON te.timesheet_id = t.id
+              AND te.deleted_at IS NULL
+             LEFT JOIN operations_project_assignment pa
+               ON pa.id = te.project_assignment_id
+             LEFT JOIN operations_project p
+               ON p.id = pa.project_id
+             LEFT JOIN operations_time_off_request tor
+               ON a.target_type = 'time_off_request'
+              AND tor.id = a.target_id
+             LEFT JOIN operations_schedule_adjustment_request sar
+               ON a.target_type = 'schedule_adjustment_request'
+              AND sar.id = a.target_id
+            WHERE a.deleted_at IS NULL
+              AND a.status = 'pending'
+              AND a.approver_collaborator_id = $1
+            GROUP BY a.id, requester.id, approver.id, t.id, tor.id, sar.id
+            ORDER BY a.submitted_at DESC, a.id DESC`,
+          [actor.collaboratorId]
+        ),
+        this.queryRows(
+          `SELECT tor.id,
+                  tor.collaborator_id AS "collaboratorId",
+                  c.display_name AS "collaboratorName",
+                  tor.request_type AS "requestType",
+                  tor.start_date AS "startDate",
+                  tor.end_date AS "endDate",
+                  tor.total_days AS "totalDays",
+                  tor.status,
+                  tor.reason,
+                  tor.submitted_at AS "submittedAt",
+                  tor.reviewed_at AS "reviewedAt",
+                  approval.decision_note AS "approverNote"
+             FROM operations_time_off_request tor
+             JOIN operations_collaborator c ON c.id = tor.collaborator_id
+             LEFT JOIN operations_approval approval
+               ON approval.target_type = 'time_off_request'
+              AND approval.target_id = tor.id
+              AND approval.deleted_at IS NULL
+            WHERE tor.deleted_at IS NULL
+              AND tor.status = 'submitted'
+              AND tor.collaborator_id = ANY($1::int[])
+            ORDER BY tor.start_date ASC, tor.id ASC`,
+          [actor.teamCollaboratorIds]
+        ),
+        this.queryRows(
+          `SELECT sar.id,
+                  sar.collaborator_id AS "collaboratorId",
+                  c.display_name AS "collaboratorName",
+                  sar.request_scope AS "requestScope",
+                  sar.effective_start_date AS "effectiveStartDate",
+                  sar.effective_end_date AS "effectiveEndDate",
+                  sar.status,
+                  sar.reason,
+                  sar.submitted_at AS "submittedAt",
+                  sar.reviewed_at AS "reviewedAt",
+                  approval.decision_note AS "approverNote"
+             FROM operations_schedule_adjustment_request sar
+             JOIN operations_collaborator c ON c.id = sar.collaborator_id
+             LEFT JOIN operations_approval approval
+               ON approval.target_type = 'schedule_adjustment_request'
+              AND approval.target_id = sar.id
+              AND approval.deleted_at IS NULL
+            WHERE sar.deleted_at IS NULL
+              AND sar.status = 'submitted'
+              AND sar.collaborator_id = ANY($1::int[])
+            ORDER BY sar.effective_start_date ASC, sar.id ASC`,
+          [actor.teamCollaboratorIds]
+        ),
+      ]);
+
+    const pendingItemCounts = {
+      timesheets: pendingApprovalQueue.filter((item) => item.targetType === 'timesheet')
+        .length,
+      timeOffRequests: pendingTimeOffRequests.length,
+      scheduleAdjustmentRequests: pendingScheduleAdjustmentRequests.length,
+    };
+
+    return {
+      teamMembers,
+      projectCount: (await this.getAssignedProjectIds(actor.teamCollaboratorIds))
+        .length,
+      pendingApprovals: Number(
+        (
+          await this.querySingle<{ total: string }>(
+            `SELECT COUNT(*)::text AS total
+               FROM operations_approval
+              WHERE deleted_at IS NULL
+                AND status = 'pending'
+                AND approver_collaborator_id = $1`,
+            [actor.collaboratorId]
+          )
+        )?.total ?? 0
+      ),
+      pendingItems: pendingItemCounts,
+      teamProjects,
+      pendingApprovalQueue,
+      pendingTimeOffRequests,
+      pendingScheduleAdjustmentRequests,
+    };
+  }
+
+  async createCollaborator(userId: number, data: CollaboratorPayload) {
+    const actor = await this.getActorContext(userId);
+    this.ensureDirector(actor);
+    this.requireFields(data, ['userId', 'code', 'displayName']);
+
+    const collaboratorId = await this.prisma.$transaction(async (tx) => {
+      const created = (await (tx as any).$queryRawUnsafe(
+        `INSERT INTO operations_collaborator (
+          user_id,
+          supervisor_collaborator_id,
+          code,
+          collaborator_type,
+          display_name,
+          department,
+          title,
+          level_label,
+          weekly_capacity_hours,
+          status,
+          joined_at,
+          left_at,
+          notes,
+          created_at,
+          updated_at
+        ) VALUES (
+          $1, $2, $3, COALESCE($4, 'other'), $5, $6, $7, $8, $9,
+          COALESCE($10, 'active'), $11, $12, $13, NOW(), NOW()
+        )
+        RETURNING id`,
+        data.userId,
+        data.supervisorCollaboratorId ?? null,
+        data.code,
+        data.collaboratorType ?? 'other',
+        data.displayName,
+        data.department ?? null,
+        data.title ?? null,
+        data.levelLabel ?? null,
+        data.weeklyCapacityHours ?? null,
+        data.status ?? 'active',
+        data.joinedAt ?? null,
+        data.leftAt ?? null,
+        data.notes ?? null
+      )) as { id: number }[];
+
+      const createdCollaboratorId = created[0]?.id;
+      await this.replaceCollaboratorScheduleDays(
+        tx as any,
+        createdCollaboratorId,
+        data.weeklySchedule
+      );
+
+      if (data.autoGenerateContractDraft !== false) {
+        await this.createHiringContractDraft(tx as any, actor.userId, {
+          collaboratorId: createdCollaboratorId,
+          collaboratorCode: data.code,
+          displayName: data.displayName,
+          collaboratorType: data.collaboratorType ?? 'other',
+          supervisorCollaboratorId: data.supervisorCollaboratorId ?? null,
+          startDate: data.joinedAt ?? null,
+          weeklyCapacityHours: data.weeklyCapacityHours ?? null,
+          compensationAmount: data.compensationAmount ?? null,
+          description: data.contractDescription ?? data.notes ?? null,
+        });
+      }
+
+      return createdCollaboratorId;
+    });
+
+    return this.getCollaboratorByIdForUser(userId, collaboratorId);
+  }
+
+  async updateCollaborator(
+    userId: number,
+    collaboratorId: number,
+    data: Partial<CollaboratorPayload>
+  ) {
+    const actor = await this.getActorContext(userId);
+    this.ensureDirector(actor);
+    await this.getCollaboratorById(collaboratorId);
+
+    const updates: string[] = [];
+    const params: unknown[] = [];
+    this.pushUpdate(updates, params, 'supervisor_collaborator_id', data.supervisorCollaboratorId);
+    this.pushUpdate(updates, params, 'code', data.code);
+    this.pushUpdate(updates, params, 'collaborator_type', data.collaboratorType);
+    this.pushUpdate(updates, params, 'display_name', data.displayName);
+    this.pushUpdate(updates, params, 'department', data.department);
+    this.pushUpdate(updates, params, 'title', data.title);
+    this.pushUpdate(updates, params, 'level_label', data.levelLabel);
+    this.pushUpdate(updates, params, 'weekly_capacity_hours', data.weeklyCapacityHours);
+    this.pushUpdate(updates, params, 'status', data.status);
+    this.pushUpdate(updates, params, 'joined_at', data.joinedAt);
+    this.pushUpdate(updates, params, 'left_at', data.leftAt);
+    this.pushUpdate(updates, params, 'notes', data.notes);
+
+    await this.prisma.$transaction(async (tx) => {
+      if (updates.length) {
+        params.push(collaboratorId);
+        await (tx as any).$executeRawUnsafe(
+          `UPDATE operations_collaborator
+              SET ${updates.join(', ')},
+                  updated_at = NOW()
+            WHERE id = $${params.length}`,
+          ...params
+        );
+      }
+
+      if (data.weeklySchedule) {
+        await this.replaceCollaboratorScheduleDays(
+          tx as any,
+          collaboratorId,
+          data.weeklySchedule
+        );
+      }
+    });
+
+    return this.getCollaboratorByIdForUser(userId, collaboratorId);
+  }
+
+  async listProjects(userId: number) {
+    const actor = await this.getActorContext(userId);
+    const filter = this.buildIdFilter(actor.visibleProjectIds, 'p.id', actor.isDirector);
+    const assignmentParams: unknown[] = [];
+    const ownAssignmentSelect = actor.collaboratorId
+      ? `MAX(CASE WHEN pa.collaborator_id = ${this.param(
+          assignmentParams,
+          actor.collaboratorId
+        )} THEN pa.id END)::int AS "myAssignmentId",
+         MAX(CASE WHEN pa.collaborator_id = ${this.param(
+           assignmentParams,
+           actor.collaboratorId
+         )} THEN pa.role_label END) AS "myRoleLabel",`
+      : `NULL::int AS "myAssignmentId",
+         NULL::varchar AS "myRoleLabel",`;
+
+    return this.queryRows(
+      `SELECT p.id,
+              p.contract_id AS "contractId",
+              p.manager_collaborator_id AS "managerCollaboratorId",
+              p.code,
+              p.name,
+              p.client_name AS "clientName",
+              p.summary,
+              p.status,
+              p.progress_percent AS "progressPercent",
+              p.delivery_model AS "deliveryModel",
+              p.budget_amount AS "budgetAmount",
+              p.start_date AS "startDate",
+              p.end_date AS "endDate",
+              c.name AS "contractName",
+              c.status AS "contractStatus",
+              m.display_name AS "managerName",
+              ${ownAssignmentSelect}
+              COUNT(DISTINCT pa.id)::int AS "teamSize"
+         FROM operations_project p
+         LEFT JOIN operations_contract c ON c.id = p.contract_id
+         LEFT JOIN operations_collaborator m ON m.id = p.manager_collaborator_id
+         LEFT JOIN operations_project_assignment pa
+           ON pa.project_id = p.id
+          AND pa.deleted_at IS NULL
+          AND pa.status IN ('planned', 'active')
+        WHERE p.deleted_at IS NULL AND ${filter.clause}
+        GROUP BY p.id, c.id, m.id
+        ORDER BY p.name ASC`,
+      [...assignmentParams, ...filter.params]
+    );
+  }
+
+  async getProjectById(userId: number, projectId: number) {
+    const actor = await this.getActorContext(userId);
+    await this.assertProjectAccess(actor, projectId);
+    return this.getProjectDetails(projectId, actor.collaboratorId);
+  }
+
+  async createProject(userId: number, data: ProjectPayload) {
+    const actor = await this.getActorContext(userId);
+    this.ensureDirector(actor);
+    this.requireFields(data, ['code', 'name']);
+
+    const createdProjectId = await this.prisma.$transaction(async (tx) => {
+      const created = await (tx as any).$queryRawUnsafe(
+        `INSERT INTO operations_project (
+          contract_id,
+          manager_collaborator_id,
+          code,
+          name,
+          client_name,
+          summary,
+          status,
+          progress_percent,
+          delivery_model,
+          budget_amount,
+          start_date,
+          end_date,
+          created_at,
+          updated_at
+        ) VALUES (
+          $1, $2, $3, $4, $5, $6, COALESCE($7, 'planning'), $8,
+          COALESCE($9, 'project_delivery'), $10, $11, $12, NOW(), NOW()
+        )
+        RETURNING id`,
+        data.contractId ?? null,
+        data.managerCollaboratorId ?? null,
+        data.code,
+        data.name,
+        data.clientName ?? null,
+        data.summary ?? null,
+        data.status ?? 'planning',
+        data.progressPercent ?? null,
+        data.deliveryModel ?? 'project_delivery',
+        data.budgetAmount ?? null,
+        data.startDate ?? null,
+        data.endDate ?? null
+      );
+
+      const projectId = (created as { id: number }[])[0]?.id;
+
+      if (data.teamAssignments?.length) {
+        await this.replaceProjectAssignments(
+          tx as any,
+          projectId,
+          data.teamAssignments
+        );
+      }
+
+      if (!data.contractId && data.autoGenerateContractDraft !== false) {
+        const contractId = await this.createProjectContractDraft(
+          tx as any,
+          actor.userId,
+          {
+            projectId,
+            projectCode: data.code,
+            projectName: data.name,
+            clientName: data.clientName ?? data.name,
+            managerCollaboratorId: data.managerCollaboratorId ?? null,
+            startDate: data.startDate ?? null,
+            endDate: data.endDate ?? null,
+            budgetAmount: data.budgetAmount ?? null,
+            monthlyHourCap: data.monthlyHourCap ?? null,
+            billingModel: data.billingModel ?? 'time_and_material',
+            contractCode: data.contractCode ?? null,
+            contractName: data.contractName ?? null,
+            description: data.contractDescription ?? data.summary ?? null,
+          }
+        );
+
+        await (tx as any).$executeRawUnsafe(
+          `UPDATE operations_project
+              SET contract_id = $1,
+                  updated_at = NOW()
+            WHERE id = $2`,
+          contractId,
+          projectId
+        );
+      }
+
+      return projectId;
+    });
+
+    return this.getProjectById(userId, createdProjectId);
+  }
+
+  async updateProject(userId: number, projectId: number, data: Partial<ProjectPayload>) {
+    const actor = await this.getActorContext(userId);
+    this.ensureDirector(actor);
+    await this.getProjectById(userId, projectId);
+
+    const updates: string[] = [];
+    const params: unknown[] = [];
+    this.pushUpdate(updates, params, 'contract_id', data.contractId);
+    this.pushUpdate(updates, params, 'manager_collaborator_id', data.managerCollaboratorId);
+    this.pushUpdate(updates, params, 'code', data.code);
+    this.pushUpdate(updates, params, 'name', data.name);
+    this.pushUpdate(updates, params, 'client_name', data.clientName);
+    this.pushUpdate(updates, params, 'summary', data.summary);
+    this.pushUpdate(updates, params, 'status', data.status);
+    this.pushUpdate(updates, params, 'progress_percent', data.progressPercent);
+    this.pushUpdate(updates, params, 'delivery_model', data.deliveryModel);
+    this.pushUpdate(updates, params, 'budget_amount', data.budgetAmount);
+    this.pushUpdate(updates, params, 'start_date', data.startDate);
+    this.pushUpdate(updates, params, 'end_date', data.endDate);
+
+    await this.prisma.$transaction(async (tx) => {
+      if (updates.length) {
+        params.push(projectId);
+        await (tx as any).$executeRawUnsafe(
+          `UPDATE operations_project
+              SET ${updates.join(', ')},
+                  updated_at = NOW()
+            WHERE id = $${params.length}`,
+          ...params
+        );
+      }
+
+      if (data.teamAssignments) {
+        await this.replaceProjectAssignments(
+          tx as any,
+          projectId,
+          data.teamAssignments
+        );
+      }
+    });
+
+    return this.getProjectById(userId, projectId);
+  }
+
+  async listContracts(userId: number) {
+    const actor = await this.getActorContext(userId);
+    const params: unknown[] = [];
+    const accessClause = actor.isDirector
+      ? 'c.deleted_at IS NULL'
+      : `c.deleted_at IS NULL AND (
+          c.related_collaborator_id = ANY(${this.param(params, actor.visibleCollaboratorIds)}::int[])
+          OR EXISTS (
+            SELECT 1
+              FROM operations_project p_access
+             WHERE p_access.contract_id = c.id
+               AND p_access.deleted_at IS NULL
+               AND p_access.id = ANY(${this.param(params, actor.visibleProjectIds)}::int[])
+          )
+        )`;
+
+    return this.queryRows(
+      `SELECT c.id,
+              c.code,
+              c.name,
+              c.contract_category AS "contractCategory",
+              c.contract_type AS "contractType",
+              c.client_name AS "clientName",
+              c.signature_status AS "signatureStatus",
+              c.is_active AS "isActive",
+              c.billing_model AS "billingModel",
+              c.account_manager_collaborator_id AS "accountManagerCollaboratorId",
+              c.related_collaborator_id AS "relatedCollaboratorId",
+              c.origin_type AS "originType",
+              c.origin_id AS "originId",
+              c.start_date AS "startDate",
+              c.end_date AS "endDate",
+              c.signed_at AS "signedAt",
+              c.effective_date AS "effectiveDate",
+              c.budget_amount AS "budgetAmount",
+              c.monthly_hour_cap AS "monthlyHourCap",
+              c.status,
+              c.description,
+              m.display_name AS "accountManagerName",
+              linked.display_name AS "relatedCollaboratorName",
+              COALESCE(primary_party.display_name, linked.display_name, c.client_name) AS "mainRelatedPartyName",
+              COALESCE(financials.value_amount, 0) AS "valueAmount",
+              COALESCE(financials.payment_amount, 0) AS "paymentAmount",
+              COALESCE(financials.revenue_amount, 0) AS "revenueAmount",
+              COALESCE(financials.fine_amount, 0) AS "fineAmount",
+              COALESCE(pdf_document.file_name, '') AS "currentPdfFileName",
+              COUNT(DISTINCT p.id)::int AS "projectCount"
+         FROM operations_contract c
+         LEFT JOIN operations_collaborator m ON m.id = c.account_manager_collaborator_id
+         LEFT JOIN operations_collaborator linked ON linked.id = c.related_collaborator_id
+         LEFT JOIN LATERAL (
+           SELECT cp.display_name
+             FROM operations_contract_party cp
+            WHERE cp.contract_id = c.id
+              AND cp.deleted_at IS NULL
+            ORDER BY cp.is_primary DESC, cp.id ASC
+            LIMIT 1
+         ) primary_party ON TRUE
+         LEFT JOIN LATERAL (
+           SELECT
+             SUM(CASE WHEN term_type = 'value' THEN amount ELSE 0 END) AS value_amount,
+             SUM(CASE WHEN term_type = 'payment' THEN amount ELSE 0 END) AS payment_amount,
+             SUM(CASE WHEN term_type = 'revenue' THEN amount ELSE 0 END) AS revenue_amount,
+             SUM(CASE WHEN term_type = 'fine' THEN amount ELSE 0 END) AS fine_amount
+           FROM operations_contract_financial_term ft
+          WHERE ft.contract_id = c.id
+            AND ft.deleted_at IS NULL
+         ) financials ON TRUE
+         LEFT JOIN LATERAL (
+           SELECT cd.file_name
+             FROM operations_contract_document cd
+            WHERE cd.contract_id = c.id
+              AND cd.deleted_at IS NULL
+              AND cd.is_current = true
+              AND cd.document_type IN ('uploaded_pdf', 'generated_pdf')
+            ORDER BY cd.id DESC
+            LIMIT 1
+         ) pdf_document ON TRUE
+         LEFT JOIN operations_project p
+           ON p.contract_id = c.id
+          AND p.deleted_at IS NULL
+        WHERE ${accessClause}
+        GROUP BY c.id, m.id, linked.id
+        ORDER BY c.name ASC`,
+      params
+    );
+  }
+
+  async getContractById(userId: number, contractId: number) {
+    const actor = await this.getActorContext(userId);
+    const contract = await this.querySingle(
+      `SELECT c.id,
+              c.code,
+              c.name,
+              c.contract_category AS "contractCategory",
+              c.contract_type AS "contractType",
+              c.client_name AS "clientName",
+              c.signature_status AS "signatureStatus",
+              c.is_active AS "isActive",
+              c.billing_model AS "billingModel",
+              c.account_manager_collaborator_id AS "accountManagerCollaboratorId",
+              c.related_collaborator_id AS "relatedCollaboratorId",
+              c.origin_type AS "originType",
+              c.origin_id AS "originId",
+              c.start_date AS "startDate",
+              c.end_date AS "endDate",
+              c.signed_at AS "signedAt",
+              c.effective_date AS "effectiveDate",
+              c.budget_amount AS "budgetAmount",
+              c.monthly_hour_cap AS "monthlyHourCap",
+              c.status,
+              c.description,
+              c.content_html AS "contentHtml",
+              m.display_name AS "accountManagerName",
+              linked.display_name AS "relatedCollaboratorName"
+         FROM operations_contract c
+         LEFT JOIN operations_collaborator m ON m.id = c.account_manager_collaborator_id
+         LEFT JOIN operations_collaborator linked ON linked.id = c.related_collaborator_id
+        WHERE c.id = $1
+          AND c.deleted_at IS NULL`,
+      [contractId]
+    );
+    if (!contract) {
+      throw new NotFoundException('Contract not found.');
+    }
+
+    if (!actor.isDirector) {
+      const access = await this.querySingle<{ exists: boolean }>(
+        `SELECT EXISTS (
+            SELECT 1
+              FROM operations_contract c
+             WHERE c.id = $1
+               AND c.deleted_at IS NULL
+               AND (
+                 c.related_collaborator_id = ANY($2::int[])
+                 OR EXISTS (
+                   SELECT 1
+                     FROM operations_project p
+                    WHERE p.contract_id = c.id
+                      AND p.deleted_at IS NULL
+                      AND p.id = ANY($3::int[])
+                 )
+               )
+          ) AS exists`,
+        [contractId, actor.visibleCollaboratorIds, actor.visibleProjectIds]
+      );
+      if (!access?.exists) {
+        throw new ForbiddenException('You do not have access to this contract.');
+      }
+    }
+
+    const [projects, scheduleSummary, parties, signatures, financialTerms, documents, revisions, history] =
+      await Promise.all([
+        this.queryRows(
+          `SELECT id, code, name, status
+             FROM operations_project
+            WHERE contract_id = $1
+              AND deleted_at IS NULL
+            ORDER BY name ASC`,
+          [contractId]
+        ),
+        contract.relatedCollaboratorId
+          ? this.queryRows(
+              `SELECT weekday,
+                      is_working_day AS "isWorkingDay",
+                      start_time AS "startTime",
+                      end_time AS "endTime",
+                      break_minutes AS "breakMinutes"
+                 FROM operations_collaborator_schedule_day
+                WHERE collaborator_id = $1
+                  AND deleted_at IS NULL
+                ORDER BY id ASC`,
+              [contract.relatedCollaboratorId]
+            )
+          : Promise.resolve([]),
+        this.queryRows(
+          `SELECT id,
+                  party_role AS "partyRole",
+                  party_type AS "partyType",
+                  display_name AS "displayName",
+                  document_number AS "documentNumber",
+                  email,
+                  phone,
+                  is_primary AS "isPrimary"
+             FROM operations_contract_party
+            WHERE contract_id = $1
+              AND deleted_at IS NULL
+            ORDER BY is_primary DESC, id ASC`,
+          [contractId]
+        ),
+        this.queryRows(
+          `SELECT id,
+                  signer_name AS "signerName",
+                  signer_role AS "signerRole",
+                  signer_email AS "signerEmail",
+                  signer_status AS status,
+                  signed_at AS "signedAt"
+             FROM operations_contract_signature
+            WHERE contract_id = $1
+              AND deleted_at IS NULL
+            ORDER BY id ASC`,
+          [contractId]
+        ),
+        this.queryRows(
+          `SELECT id,
+                  term_type AS "termType",
+                  label,
+                  amount,
+                  recurrence,
+                  due_day AS "dueDay",
+                  notes
+             FROM operations_contract_financial_term
+            WHERE contract_id = $1
+              AND deleted_at IS NULL
+            ORDER BY id ASC`,
+          [contractId]
+        ),
+        this.queryRows(
+          `SELECT id,
+                  document_type AS "documentType",
+                  file_name AS "fileName",
+                  mime_type AS "mimeType",
+                  file_content_base64 AS "fileContentBase64",
+                  is_current AS "isCurrent",
+                  notes,
+                  created_at AS "createdAt"
+             FROM operations_contract_document
+            WHERE contract_id = $1
+              AND deleted_at IS NULL
+            ORDER BY is_current DESC, id DESC`,
+          [contractId]
+        ),
+        this.queryRows(
+          `SELECT id,
+                  revision_type AS "revisionType",
+                  title,
+                  effective_date AS "effectiveDate",
+                  status,
+                  summary
+             FROM operations_contract_revision
+            WHERE contract_id = $1
+              AND deleted_at IS NULL
+            ORDER BY effective_date DESC NULLS LAST, id DESC`,
+          [contractId]
+        ),
+        this.queryRows(
+          `SELECT id,
+                  actor_user_id AS "actorUserId",
+                  action,
+                  note,
+                  metadata_json AS "metadataJson",
+                  created_at AS "createdAt"
+             FROM operations_contract_history
+            WHERE contract_id = $1
+            ORDER BY id DESC`,
+          [contractId]
+        ),
+      ]);
+
+    return {
+      ...contract,
+      mainRelatedPartyName:
+        parties.find((party: any) => party.isPrimary)?.displayName ??
+        contract.relatedCollaboratorName ??
+        contract.clientName,
+      projects,
+      scheduleSummary,
+      parties,
+      signatures,
+      financialTerms,
+      documents,
+      revisions,
+      history,
+    };
+  }
+
+  async createContract(userId: number, data: ContractPayload) {
+    const actor = await this.getActorContext(userId);
+    this.ensureDirector(actor);
+    this.requireFields(data, ['code', 'name', 'clientName', 'startDate']);
+
+    const createdId = await this.prisma.$transaction(async (tx) => {
+      const created = await (tx as any).$queryRawUnsafe(
+        `INSERT INTO operations_contract (
+          code,
+          name,
+          contract_category,
+          contract_type,
+          client_name,
+          signature_status,
+          is_active,
+          billing_model,
+          account_manager_collaborator_id,
+          related_collaborator_id,
+          origin_type,
+          origin_id,
+          start_date,
+          end_date,
+          signed_at,
+          effective_date,
+          budget_amount,
+          monthly_hour_cap,
+          status,
+          description,
+          content_html,
+          created_at,
+          updated_at
+        ) VALUES (
+          $1, $2, COALESCE($3, 'client'), COALESCE($4, 'service_agreement'), $5, COALESCE($6, 'not_started'),
+          COALESCE($7, true), COALESCE($8, 'time_and_material'), $9, $10, COALESCE($11, 'manual'), $12, $13,
+          $14, $15, $16, $17, $18, COALESCE($19, 'draft'), $20, $21, NOW(), NOW()
+        )
+        RETURNING id`,
+        data.code,
+        data.name,
+        data.contractCategory ?? 'client',
+        data.contractType ?? 'service_agreement',
+        data.clientName,
+        data.signatureStatus ?? 'not_started',
+        data.isActive ?? true,
+        data.billingModel ?? 'time_and_material',
+        data.accountManagerCollaboratorId ?? null,
+        data.relatedCollaboratorId ?? null,
+        data.originType ?? 'manual',
+        data.originId ?? null,
+        data.startDate,
+        data.endDate ?? null,
+        data.signedAt ?? null,
+        data.effectiveDate ?? data.startDate,
+        data.budgetAmount ?? null,
+        data.monthlyHourCap ?? null,
+        data.status ?? 'draft',
+        data.description ?? null,
+        data.contentHtml ?? null
+      );
+
+      const contractId = (created as { id: number }[])[0]?.id;
+      await this.replaceContractParties(tx as any, contractId, data.parties);
+      await this.replaceContractSignatures(tx as any, contractId, data.signatures);
+      await this.replaceContractFinancialTerms(
+        tx as any,
+        contractId,
+        data.financialTerms
+      );
+      await this.replaceContractRevisions(tx as any, contractId, data.revisions);
+      if (data.replaceUploadedPdfDocument) {
+        await this.replaceContractPdfDocument(
+          tx as any,
+          contractId,
+          data.replaceUploadedPdfDocument
+        );
+      }
+      await this.insertContractHistory(
+        tx as any,
+        contractId,
+        userId,
+        'created',
+        data.originType === 'manual'
+          ? 'Manual contract created from registry.'
+          : `Contract registered from origin ${data.originType}.`
+      );
+      return contractId;
+    });
+
+    return this.getContractById(userId, createdId);
+  }
+
+  async updateContract(userId: number, contractId: number, data: Partial<ContractPayload>) {
+    const actor = await this.getActorContext(userId);
+    this.ensureDirector(actor);
+    await this.getContractById(userId, contractId);
+
+    const updates: string[] = [];
+    const params: unknown[] = [];
+    this.pushUpdate(updates, params, 'code', data.code);
+    this.pushUpdate(updates, params, 'name', data.name);
+    this.pushUpdate(updates, params, 'contract_category', data.contractCategory);
+    this.pushUpdate(updates, params, 'contract_type', data.contractType);
+    this.pushUpdate(updates, params, 'client_name', data.clientName);
+    this.pushUpdate(updates, params, 'signature_status', data.signatureStatus);
+    this.pushUpdate(updates, params, 'is_active', data.isActive);
+    this.pushUpdate(updates, params, 'billing_model', data.billingModel);
+    this.pushUpdate(updates, params, 'account_manager_collaborator_id', data.accountManagerCollaboratorId);
+    this.pushUpdate(updates, params, 'related_collaborator_id', data.relatedCollaboratorId);
+    this.pushUpdate(updates, params, 'origin_type', data.originType);
+    this.pushUpdate(updates, params, 'origin_id', data.originId);
+    this.pushUpdate(updates, params, 'start_date', data.startDate);
+    this.pushUpdate(updates, params, 'end_date', data.endDate);
+    this.pushUpdate(updates, params, 'signed_at', data.signedAt);
+    this.pushUpdate(updates, params, 'effective_date', data.effectiveDate);
+    this.pushUpdate(updates, params, 'budget_amount', data.budgetAmount);
+    this.pushUpdate(updates, params, 'monthly_hour_cap', data.monthlyHourCap);
+    this.pushUpdate(updates, params, 'status', data.status);
+    this.pushUpdate(updates, params, 'description', data.description);
+    this.pushUpdate(updates, params, 'content_html', data.contentHtml);
+
+    await this.prisma.$transaction(async (tx) => {
+      if (updates.length) {
+        params.push(contractId);
+        await (tx as any).$executeRawUnsafe(
+          `UPDATE operations_contract
+              SET ${updates.join(', ')},
+                  updated_at = NOW()
+            WHERE id = $${params.length}`,
+          ...params
+        );
+      }
+
+      if (data.parties) {
+        await this.replaceContractParties(tx as any, contractId, data.parties);
+      }
+      if (data.signatures) {
+        await this.replaceContractSignatures(
+          tx as any,
+          contractId,
+          data.signatures
+        );
+      }
+      if (data.financialTerms) {
+        await this.replaceContractFinancialTerms(
+          tx as any,
+          contractId,
+          data.financialTerms
+        );
+      }
+      if (data.revisions) {
+        await this.replaceContractRevisions(
+          tx as any,
+          contractId,
+          data.revisions
+        );
+      }
+      if (data.replaceUploadedPdfDocument) {
+        await this.replaceContractPdfDocument(
+          tx as any,
+          contractId,
+          data.replaceUploadedPdfDocument
+        );
+      }
+
+      await this.insertContractHistory(
+        tx as any,
+        contractId,
+        userId,
+        'updated',
+        'Contract registry data updated.'
+      );
+    });
+
+    return this.getContractById(userId, contractId);
+  }
+
+  async listTimesheets(userId: number) {
+    const actor = await this.getActorContext(userId);
+    const filter = this.buildIdFilter(actor.visibleCollaboratorIds, 't.collaborator_id', actor.isDirector);
+
+    const headers = await this.queryRows<{
+      id: number;
+      collaboratorId: number;
+      collaboratorName: string;
+      approverCollaboratorId: number | null;
+      approverName: string | null;
+      weekStartDate: string;
+      weekEndDate: string;
+      totalHours: number | null;
+      status: string;
+      submittedAt: string | null;
+      reviewedAt: string | null;
+      notes: string | null;
+      decisionNote: string | null;
+    }>(
+      `SELECT t.id,
+              t.collaborator_id AS "collaboratorId",
+              c.display_name AS "collaboratorName",
+              t.approver_collaborator_id AS "approverCollaboratorId",
+              a.display_name AS "approverName",
+              t.week_start_date AS "weekStartDate",
+              t.week_end_date AS "weekEndDate",
+              t.total_hours AS "totalHours",
+              t.status,
+              t.submitted_at AS "submittedAt",
+              t.reviewed_at AS "reviewedAt",
+              t.notes,
+              approval.decision_note AS "decisionNote"
+         FROM operations_timesheet t
+         JOIN operations_collaborator c ON c.id = t.collaborator_id
+         LEFT JOIN operations_collaborator a ON a.id = t.approver_collaborator_id
+         LEFT JOIN operations_approval approval
+           ON approval.target_type = 'timesheet'
+          AND approval.target_id = t.id
+          AND approval.deleted_at IS NULL
+        WHERE t.deleted_at IS NULL AND ${filter.clause}
+        ORDER BY t.week_start_date DESC, t.id DESC`,
+      filter.params
+    );
+
+    if (!headers.length) {
+      return headers;
+    }
+
+    const entries = await this.queryRows<{
+      id: number;
+      timesheetId: number;
+      projectAssignmentId: number | null;
+      projectId: number | null;
+      projectName: string | null;
+      roleLabel: string | null;
+      activityLabel: string | null;
+      workDate: string;
+      hours: number;
+      description: string | null;
+    }>(
+      `SELECT e.id,
+              e.timesheet_id AS "timesheetId",
+              e.project_assignment_id AS "projectAssignmentId",
+              pa.project_id AS "projectId",
+              p.name AS "projectName",
+              pa.role_label AS "roleLabel",
+              e.activity_label AS "activityLabel",
+              e.work_date AS "workDate",
+              e.hours,
+              e.description
+         FROM operations_timesheet_entry e
+         LEFT JOIN operations_project_assignment pa ON pa.id = e.project_assignment_id
+         LEFT JOIN operations_project p ON p.id = pa.project_id
+        WHERE e.deleted_at IS NULL
+          AND e.timesheet_id = ANY($1::int[])
+        ORDER BY e.work_date ASC, e.id ASC`,
+      [headers.map((item) => item.id)]
+    );
+
+    const grouped = this.groupBy(entries, 'timesheetId');
+    return headers.map((timesheet) => ({
+      ...timesheet,
+      entries: grouped[timesheet.id] ?? [],
+    }));
+  }
+
+  async createTimesheet(userId: number, data: TimesheetPayload) {
+    const actor = await this.getActorContext(userId);
+    this.ensureCollaborator(actor);
+    this.requireFields(data, ['weekStartDate', 'weekEndDate']);
+
+    const collaboratorId =
+      actor.isDirector && data.collaboratorId
+        ? data.collaboratorId
+        : actor.collaboratorId;
+
+    if (!collaboratorId) {
+      throw new BadRequestException('Collaborator context is required.');
+    }
+    if (!actor.isDirector && collaboratorId !== actor.collaboratorId) {
+      throw new ForbiddenException('You can only create your own timesheets.');
+    }
+
+    const collaborator = await this.getCollaboratorById(collaboratorId);
+    const created = await this.prisma.$transaction(async (tx) => {
+      const row = (await (tx as any).$queryRawUnsafe(
+        `INSERT INTO operations_timesheet (
+          collaborator_id,
+          approver_collaborator_id,
+          week_start_date,
+          week_end_date,
+          notes,
+          status,
+          created_at,
+          updated_at
+        ) VALUES ($1, $2, $3, $4, $5, 'draft', NOW(), NOW())
+        RETURNING id`,
+        collaboratorId,
+        collaborator.supervisorId ?? null,
+        data.weekStartDate,
+        data.weekEndDate,
+        data.notes ?? null
+      )) as { id: number }[];
+      const timesheetId = row[0]?.id;
+      await this.replaceTimesheetEntries(
+        tx as any,
+        timesheetId,
+        data.entries ?? [],
+        collaboratorId
+      );
+      await this.refreshTimesheetTotal(tx as any, timesheetId);
+      return timesheetId;
+    });
+
+    return this.listSingleTimesheet(actor, created);
+  }
+
+  async updateTimesheet(
+    userId: number,
+    timesheetId: number,
+    data: Partial<TimesheetPayload>
+  ) {
+    const actor = await this.getActorContext(userId);
+    const current = await this.getTimesheetById(timesheetId);
+
+    if (!actor.isDirector && current.collaboratorId !== actor.collaboratorId) {
+      throw new ForbiddenException('You can only update your own timesheets.');
+    }
+    if (!actor.isDirector && !['draft', 'rejected'].includes(current.status)) {
+      throw new BadRequestException('Only draft or rejected timesheets can be edited.');
+    }
+
+    await this.prisma.$transaction(async (tx) => {
+      const updates: string[] = [];
+      const params: unknown[] = [];
+      this.pushUpdate(updates, params, 'week_start_date', data.weekStartDate);
+      this.pushUpdate(updates, params, 'week_end_date', data.weekEndDate);
+      this.pushUpdate(updates, params, 'notes', data.notes);
+
+      if (updates.length) {
+        params.push(timesheetId);
+        await (tx as any).$executeRawUnsafe(
+          `UPDATE operations_timesheet
+              SET ${updates.join(', ')},
+                  updated_at = NOW()
+            WHERE id = $${params.length}`,
+          ...params
+        );
+      }
+
+      if (data.entries) {
+        await this.replaceTimesheetEntries(
+          tx as any,
+          timesheetId,
+          data.entries,
+          current.collaboratorId
+        );
+      }
+
+      await this.refreshTimesheetTotal(tx as any, timesheetId);
+    });
+
+    return this.listSingleTimesheet(actor, timesheetId);
+  }
+
+  async submitTimesheet(userId: number, timesheetId: number) {
+    const actor = await this.getActorContext(userId);
+    const current = await this.getTimesheetById(timesheetId);
+    if (!actor.isDirector && current.collaboratorId !== actor.collaboratorId) {
+      throw new ForbiddenException('You can only submit your own timesheets.');
+    }
+    if (!actor.isDirector && !['draft', 'rejected'].includes(current.status)) {
+      throw new BadRequestException('Only draft or rejected timesheets can be submitted.');
+    }
+
+    const collaborator = await this.getCollaboratorById(current.collaboratorId);
+    const approverId =
+      current.approverCollaboratorId ?? collaborator.supervisorId ?? null;
+
+    await this.prisma.$transaction(async (tx) => {
+      await (tx as any).$executeRawUnsafe(
+        `UPDATE operations_timesheet
+            SET status = 'submitted',
+                approver_collaborator_id = $1,
+                submitted_at = NOW(),
+                updated_at = NOW()
+          WHERE id = $2`,
+        approverId,
+        timesheetId
+      );
+      await this.upsertApproval(tx as any, {
+        targetType: 'timesheet',
+        targetId: timesheetId,
+        requesterCollaboratorId: current.collaboratorId,
+        approverCollaboratorId: approverId,
+      });
+    });
+
+    return this.listSingleTimesheet(actor, timesheetId);
+  }
+
+  async listTimeOffRequests(userId: number) {
+    const actor = await this.getActorContext(userId);
+    const filter = this.buildIdFilter(actor.visibleCollaboratorIds, 'tor.collaborator_id', actor.isDirector);
+
+    return this.queryRows(
+      `SELECT tor.id,
+              tor.collaborator_id AS "collaboratorId",
+              c.display_name AS "collaboratorName",
+              tor.approver_collaborator_id AS "approverCollaboratorId",
+              a.display_name AS "approverName",
+              tor.request_type AS "requestType",
+              tor.start_date AS "startDate",
+              tor.end_date AS "endDate",
+              tor.total_days AS "totalDays",
+              tor.status,
+              tor.reason,
+              tor.submitted_at AS "submittedAt",
+              tor.reviewed_at AS "reviewedAt",
+              approval.decision_note AS "approverNote"
+         FROM operations_time_off_request tor
+         JOIN operations_collaborator c ON c.id = tor.collaborator_id
+         LEFT JOIN operations_collaborator a ON a.id = tor.approver_collaborator_id
+         LEFT JOIN operations_approval approval
+           ON approval.target_type = 'time_off_request'
+          AND approval.target_id = tor.id
+          AND approval.deleted_at IS NULL
+        WHERE tor.deleted_at IS NULL AND ${filter.clause}
+        ORDER BY tor.start_date DESC, tor.id DESC`,
+      filter.params
+    );
+  }
+
+  async createTimeOffRequest(userId: number, data: TimeOffPayload) {
+    const actor = await this.getActorContext(userId);
+    this.ensureCollaborator(actor);
+    this.requireFields(data, ['startDate', 'endDate']);
+
+    const collaboratorId =
+      actor.isDirector && data.collaboratorId
+        ? data.collaboratorId
+        : actor.collaboratorId;
+    if (!collaboratorId) {
+      throw new BadRequestException('Collaborator context is required.');
+    }
+    if (!actor.isDirector && collaboratorId !== actor.collaboratorId) {
+      throw new ForbiddenException('You can only create your own time-off requests.');
+    }
+
+    const collaborator = await this.getCollaboratorById(collaboratorId);
+    const created = await this.prisma.$transaction(async (tx) => {
+      const row = (await (tx as any).$queryRawUnsafe(
+        `INSERT INTO operations_time_off_request (
+          collaborator_id,
+          approver_collaborator_id,
+          request_type,
+          start_date,
+          end_date,
+          total_days,
+          status,
+          reason,
+          submitted_at,
+          created_at,
+          updated_at
+        ) VALUES ($1, $2, COALESCE($3, 'vacation'), $4, $5, $6, 'submitted', $7, NOW(), NOW(), NOW())
+        RETURNING id`,
+        collaboratorId,
+        collaborator.supervisorId ?? null,
+        data.requestType ?? 'vacation',
+        data.startDate,
+        data.endDate,
+        data.totalDays ?? null,
+        data.reason ?? null
+      )) as { id: number }[];
+      const requestId = row[0]?.id;
+      await this.upsertApproval(tx as any, {
+        targetType: 'time_off_request',
+        targetId: requestId,
+        requesterCollaboratorId: collaboratorId,
+        approverCollaboratorId: collaborator.supervisorId ?? null,
+      });
+      return requestId;
+    });
+
+    return this.querySingle(
+      `SELECT id,
+              collaborator_id AS "collaboratorId",
+              approver_collaborator_id AS "approverCollaboratorId",
+              request_type AS "requestType",
+              start_date AS "startDate",
+              end_date AS "endDate",
+              total_days AS "totalDays",
+              status,
+              reason,
+              submitted_at AS "submittedAt",
+              reviewed_at AS "reviewedAt"
+         FROM operations_time_off_request
+        WHERE id = $1`,
+      [created]
+    );
+  }
+
+  async listScheduleAdjustments(userId: number) {
+    const actor = await this.getActorContext(userId);
+    const filter = this.buildIdFilter(actor.visibleCollaboratorIds, 'sar.collaborator_id', actor.isDirector);
+
+    const requests = await this.queryRows<{
+      id: number;
+      collaboratorId: number;
+      collaboratorName: string;
+      approverCollaboratorId: number | null;
+      approverName: string | null;
+      requestScope: string;
+      effectiveStartDate: string;
+      effectiveEndDate: string | null;
+      status: string;
+      reason: string | null;
+      submittedAt: string | null;
+      reviewedAt: string | null;
+      approverNote: string | null;
+    }>(
+      `SELECT sar.id,
+              sar.collaborator_id AS "collaboratorId",
+              c.display_name AS "collaboratorName",
+              sar.approver_collaborator_id AS "approverCollaboratorId",
+              a.display_name AS "approverName",
+              sar.request_scope AS "requestScope",
+              sar.effective_start_date AS "effectiveStartDate",
+              sar.effective_end_date AS "effectiveEndDate",
+              sar.status,
+              sar.reason,
+              sar.submitted_at AS "submittedAt",
+              sar.reviewed_at AS "reviewedAt",
+              approval.decision_note AS "approverNote"
+         FROM operations_schedule_adjustment_request sar
+         JOIN operations_collaborator c ON c.id = sar.collaborator_id
+         LEFT JOIN operations_collaborator a ON a.id = sar.approver_collaborator_id
+         LEFT JOIN operations_approval approval
+           ON approval.target_type = 'schedule_adjustment_request'
+          AND approval.target_id = sar.id
+          AND approval.deleted_at IS NULL
+        WHERE sar.deleted_at IS NULL AND ${filter.clause}
+        ORDER BY sar.effective_start_date DESC, sar.id DESC`,
+      filter.params
+    );
+
+    if (!requests.length) {
+      return requests;
+    }
+
+    const days = await this.queryRows<{
+      requestId: number;
+      weekday: string;
+      isWorkingDay: boolean;
+      startTime: string | null;
+      endTime: string | null;
+      breakMinutes: number | null;
+    }>(
+      `SELECT schedule_adjustment_request_id AS "requestId",
+              weekday,
+              is_working_day AS "isWorkingDay",
+              start_time AS "startTime",
+              end_time AS "endTime",
+              break_minutes AS "breakMinutes"
+         FROM operations_schedule_adjustment_day
+        WHERE schedule_adjustment_request_id = ANY($1::int[])
+        ORDER BY id ASC`,
+      [requests.map((item) => item.id)]
+    );
+
+    const currentSchedule = await this.queryRows<{
+      collaboratorId: number;
+      weekday: string;
+      isWorkingDay: boolean;
+      startTime: string | null;
+      endTime: string | null;
+      breakMinutes: number | null;
+    }>(
+      `SELECT collaborator_id AS "collaboratorId",
+              weekday,
+              is_working_day AS "isWorkingDay",
+              start_time AS "startTime",
+              end_time AS "endTime",
+              break_minutes AS "breakMinutes"
+         FROM operations_collaborator_schedule_day
+        WHERE collaborator_id = ANY($1::int[])
+        ORDER BY id ASC`,
+      [this.uniqueNumbers(requests.map((item) => item.collaboratorId))]
+    );
+
+    const grouped = this.groupBy(days, 'requestId');
+    const currentScheduleByCollaborator = this.groupBy(
+      currentSchedule,
+      'collaboratorId'
+    );
+    return requests.map((request) => ({
+      ...request,
+      days: grouped[request.id] ?? [],
+      currentSchedule: currentScheduleByCollaborator[request.collaboratorId] ?? [],
+    }));
+  }
+
+  async createScheduleAdjustmentRequest(
+    userId: number,
+    data: ScheduleAdjustmentPayload
+  ) {
+    const actor = await this.getActorContext(userId);
+    this.ensureCollaborator(actor);
+    this.requireFields(data as unknown as Record<string, unknown>, ['effectiveStartDate', 'days']);
+    if (!Array.isArray(data.days) || data.days.length === 0) {
+      throw new BadRequestException('At least one schedule day is required.');
+    }
+
+    const collaboratorId =
+      actor.isDirector && data.collaboratorId
+        ? data.collaboratorId
+        : actor.collaboratorId;
+    if (!collaboratorId) {
+      throw new BadRequestException('Collaborator context is required.');
+    }
+    if (!actor.isDirector && collaboratorId !== actor.collaboratorId) {
+      throw new ForbiddenException(
+        'You can only create your own schedule adjustments.'
+      );
+    }
+
+    const collaborator = await this.getCollaboratorById(collaboratorId);
+    const created = await this.prisma.$transaction(async (tx) => {
+      const row = (await (tx as any).$queryRawUnsafe(
+        `INSERT INTO operations_schedule_adjustment_request (
+          collaborator_id,
+          approver_collaborator_id,
+          request_scope,
+          effective_start_date,
+          effective_end_date,
+          status,
+          reason,
+          submitted_at,
+          created_at,
+          updated_at
+        ) VALUES (
+          $1, $2, COALESCE($3, 'temporary'), $4, $5, 'submitted', $6, NOW(), NOW(), NOW()
+        )
+        RETURNING id`,
+        collaboratorId,
+        collaborator.supervisorId ?? null,
+        data.requestScope ?? 'temporary',
+        data.effectiveStartDate,
+        data.effectiveEndDate ?? null,
+        data.reason ?? null
+      )) as { id: number }[];
+      const requestId = row[0]?.id;
+
+      for (const day of data.days) {
+        await (tx as any).$executeRawUnsafe(
+          `INSERT INTO operations_schedule_adjustment_day (
+            schedule_adjustment_request_id,
+            weekday,
+            is_working_day,
+            start_time,
+            end_time,
+            break_minutes,
+            created_at,
+            updated_at
+          ) VALUES ($1, $2, $3, $4, $5, $6, NOW(), NOW())`,
+          requestId,
+          day.weekday,
+          day.isWorkingDay ?? true,
+          day.startTime ?? null,
+          day.endTime ?? null,
+          day.breakMinutes ?? null
+        );
+      }
+
+      await this.upsertApproval(tx as any, {
+        targetType: 'schedule_adjustment_request',
+        targetId: requestId,
+        requesterCollaboratorId: collaboratorId,
+        approverCollaboratorId: collaborator.supervisorId ?? null,
+      });
+      return requestId;
+    });
+
+    return this.querySingle(
+      `SELECT id,
+              collaborator_id AS "collaboratorId",
+              approver_collaborator_id AS "approverCollaboratorId",
+              request_scope AS "requestScope",
+              effective_start_date AS "effectiveStartDate",
+              effective_end_date AS "effectiveEndDate",
+              status,
+              reason,
+              submitted_at AS "submittedAt",
+              reviewed_at AS "reviewedAt"
+         FROM operations_schedule_adjustment_request
+        WHERE id = $1`,
+      [created]
+    );
+  }
+
+  async listApprovals(userId: number) {
+    const actor = await this.getActorContext(userId);
+    this.ensureSupervisor(actor);
+
+    const params: unknown[] = [];
+    const clause = actor.isDirector
+      ? 'a.deleted_at IS NULL'
+      : `a.deleted_at IS NULL AND a.approver_collaborator_id = ${this.param(
+          params,
+          actor.collaboratorId
+        )}`;
+
+    return this.queryRows(
+      `SELECT a.id,
+              a.target_type AS "targetType",
+              a.target_id AS "targetId",
+              a.requester_collaborator_id AS "requesterCollaboratorId",
+              requester.display_name AS "requesterName",
+              a.approver_collaborator_id AS "approverCollaboratorId",
+              approver.display_name AS "approverName",
+              a.status,
+              a.submitted_at AS "submittedAt",
+              a.decided_at AS "decidedAt",
+              a.decision_note AS "decisionNote",
+              t.week_start_date AS "timesheetWeekStartDate",
+              t.week_end_date AS "timesheetWeekEndDate",
+              t.total_hours AS "timesheetTotalHours",
+              COALESCE(
+                STRING_AGG(DISTINCT p.name, ', ') FILTER (WHERE p.name IS NOT NULL),
+                ''
+              ) AS "timesheetProjectNames",
+              tor.request_type AS "timeOffType",
+              tor.start_date AS "timeOffStartDate",
+              tor.end_date AS "timeOffEndDate",
+              tor.reason AS "timeOffReason",
+              sar.request_scope AS "scheduleRequestScope",
+              sar.effective_start_date AS "scheduleStartDate",
+              sar.effective_end_date AS "scheduleEndDate",
+              sar.reason AS "scheduleReason"
+         FROM operations_approval a
+         JOIN operations_collaborator requester
+           ON requester.id = a.requester_collaborator_id
+         LEFT JOIN operations_collaborator approver
+           ON approver.id = a.approver_collaborator_id
+         LEFT JOIN operations_timesheet t
+           ON a.target_type = 'timesheet'
+          AND t.id = a.target_id
+         LEFT JOIN operations_timesheet_entry te
+           ON te.timesheet_id = t.id
+          AND te.deleted_at IS NULL
+         LEFT JOIN operations_project_assignment pa
+           ON pa.id = te.project_assignment_id
+         LEFT JOIN operations_project p
+           ON p.id = pa.project_id
+         LEFT JOIN operations_time_off_request tor
+           ON a.target_type = 'time_off_request'
+          AND tor.id = a.target_id
+         LEFT JOIN operations_schedule_adjustment_request sar
+           ON a.target_type = 'schedule_adjustment_request'
+          AND sar.id = a.target_id
+        WHERE ${clause}
+        GROUP BY a.id, requester.id, approver.id, t.id, tor.id, sar.id
+        ORDER BY a.submitted_at DESC, a.id DESC`,
+      params
+    );
+  }
+
+  async approve(userId: number, approvalId: number, data: DecisionPayload) {
+    return this.decideApproval(userId, approvalId, 'approve', data);
+  }
+
+  async reject(userId: number, approvalId: number, data: DecisionPayload) {
+    return this.decideApproval(userId, approvalId, 'reject', data);
+  }
+
+  async publishAccountsPayableReference(
+    userId: number,
+    data: PublishAccountsPayableReferencePayload,
+  ) {
+    const actor = await this.getActorContext(userId);
+    this.ensureSupervisor(actor);
+
+    const sourceEntityId = String(data?.sourceEntityId || '').trim();
+    const sourceEntityType =
+      String(data?.sourceEntityType || '').trim() ||
+      'operations_payable_request';
+    const personId = Number(data?.personId);
+    const totalAmount = Number(data?.totalAmount);
+    const dueDate = String(data?.dueDate || '').trim();
+    const documentNumber = String(data?.documentNumber || '').trim();
+    const locale = String(data?.locale || '').trim() || 'en';
+
+    if (!sourceEntityId) {
+      throw new BadRequestException('sourceEntityId is required.');
+    }
+    if (!Number.isInteger(personId) || personId <= 0) {
+      throw new BadRequestException('personId must be a positive integer.');
+    }
+    if (!Number.isFinite(totalAmount) || totalAmount <= 0) {
+      throw new BadRequestException('totalAmount must be greater than zero.');
+    }
+    if (!dueDate || Number.isNaN(new Date(dueDate).getTime())) {
+      throw new BadRequestException('dueDate must be a valid ISO date string.');
+    }
+    if (!documentNumber) {
+      throw new BadRequestException('documentNumber is required.');
+    }
+
+    const outboxEvent = await this.integrationApi.publishEvent({
+      eventName: 'operations.accounts_payable.requested',
+      sourceModule: 'operations',
+      aggregateType: sourceEntityType,
+      aggregateId: sourceEntityId,
+      payload: {
+        sourceEntityType,
+        sourceEntityId,
+        locale,
+        requestedByUserId: userId,
+        payable: {
+          personId,
+          dueDate,
+          totalAmount,
+          documentNumber,
+          description: data?.description ?? null,
+          paymentChannel: data?.paymentChannel ?? null,
+          financeCategoryId: data?.financeCategoryId ?? null,
+          costCenterId: data?.costCenterId ?? null,
+        },
+      },
+    });
+
+    return {
+      queued: true,
+      eventId: outboxEvent.id,
+      eventName: outboxEvent.eventName,
+      sourceEntityType,
+      sourceEntityId,
+    };
+  }
+
+  private async decideApproval(
+    userId: number,
+    approvalId: number,
+    action: ApprovalAction,
+    data: DecisionPayload
+  ) {
+    const actor = await this.getActorContext(userId);
+    this.ensureSupervisor(actor);
+
+    const approval = await this.querySingle<{
+      id: number;
+      targetType: ApprovalTargetType;
+      targetId: number;
+      requesterCollaboratorId: number;
+      approverCollaboratorId: number | null;
+      status: string;
+    }>(
+      `SELECT id,
+              target_type AS "targetType",
+              target_id AS "targetId",
+              requester_collaborator_id AS "requesterCollaboratorId",
+              approver_collaborator_id AS "approverCollaboratorId",
+              status
+         FROM operations_approval
+        WHERE id = $1
+          AND deleted_at IS NULL`,
+      [approvalId]
+    );
+    if (!approval) {
+      throw new NotFoundException('Approval not found.');
+    }
+    if (!actor.isDirector && approval.approverCollaboratorId !== actor.collaboratorId) {
+      throw new ForbiddenException('You cannot decide this approval.');
+    }
+    if (approval.status !== 'pending') {
+      throw new BadRequestException('Only pending approvals can be decided.');
+    }
+
+    const nextStatus = action === 'approve' ? 'approved' : 'rejected';
+
+    await this.prisma.$transaction(async (tx) => {
+      await (tx as any).$executeRawUnsafe(
+        `UPDATE operations_approval
+            SET status = $1,
+                decided_at = NOW(),
+                decision_note = $2,
+                updated_at = NOW()
+          WHERE id = $3`,
+        nextStatus,
+        data.note ?? null,
+        approvalId
+      );
+
+      if (approval.targetType === 'timesheet') {
+        await (tx as any).$executeRawUnsafe(
+          `UPDATE operations_timesheet
+              SET status = $1,
+                  reviewed_at = NOW(),
+                  approver_collaborator_id = $2,
+                  updated_at = NOW()
+            WHERE id = $3`,
+          nextStatus,
+          actor.collaboratorId,
+          approval.targetId
+        );
+      }
+
+      if (approval.targetType === 'time_off_request') {
+        await (tx as any).$executeRawUnsafe(
+        `UPDATE operations_time_off_request
+            SET status = $1,
+                reviewed_at = NOW(),
+                approver_collaborator_id = $2,
+                submitted_at = COALESCE(submitted_at, NOW()),
+                updated_at = NOW()
+          WHERE id = $3`,
+          nextStatus,
+          actor.collaboratorId,
+          approval.targetId
+        );
+      }
+
+      if (approval.targetType === 'schedule_adjustment_request') {
+        await (tx as any).$executeRawUnsafe(
+        `UPDATE operations_schedule_adjustment_request
+            SET status = $1,
+                reviewed_at = NOW(),
+                approver_collaborator_id = $2,
+                submitted_at = COALESCE(submitted_at, NOW()),
+                updated_at = NOW()
+          WHERE id = $3`,
+          nextStatus,
+          actor.collaboratorId,
+          approval.targetId
+        );
+      }
+
+      await this.insertApprovalHistory(
+        tx as any,
+        approvalId,
+        actor.collaboratorId,
+        nextStatus === 'approved' ? 'approved' : 'rejected',
+        data.note ?? null
+      );
+    });
+
+    return this.querySingle(
+      `SELECT id,
+              target_type AS "targetType",
+              target_id AS "targetId",
+              status,
+              decided_at AS "decidedAt",
+              decision_note AS "decisionNote"
+         FROM operations_approval
+        WHERE id = $1`,
+      [approvalId]
+    );
+  }
+
+  private async getActorContext(userId: number): Promise<ActorContext> {
+    const roleSlugs = (
+      await this.prisma.role.findMany({
+        where: {
+          role_user: {
+            some: {
+              user_id: userId,
+            },
+          },
+        },
+        select: {
+          slug: true,
+        },
+      })
+    ).map((role) => role.slug);
+
+    const isDirector =
+      roleSlugs.includes('admin') || roleSlugs.includes(DIRECTOR_ROLE);
+    const isSupervisor = isDirector || roleSlugs.includes(SUPERVISOR_ROLE);
+    const isCollaborator = isSupervisor || roleSlugs.includes(COLLABORATOR_ROLE);
+    const collaborator = await this.getCollaboratorByUserId(userId);
+
+    if (!collaborator && isCollaborator && !isDirector) {
+      throw new NotFoundException(
+        'The authenticated user does not have a linked operations collaborator profile.'
+      );
+    }
+
+    const collaboratorId = collaborator?.id ?? null;
+    const teamCollaboratorIds =
+      isSupervisor && collaboratorId
+        ? await this.getDirectReportIds(collaboratorId)
+        : [];
+
+    return {
+      userId,
+      roleSlugs,
+      collaboratorId,
+      collaboratorName: collaborator?.displayName ?? null,
+      isDirector,
+      isSupervisor,
+      isCollaborator,
+      teamCollaboratorIds,
+      visibleCollaboratorIds: this.uniqueNumbers(
+        isDirector
+          ? []
+          : [collaboratorId, ...(isSupervisor ? teamCollaboratorIds : [])]
+      ),
+      visibleProjectIds: isDirector
+        ? []
+        : await this.getAssignedProjectIds(
+            this.uniqueNumbers([
+              collaboratorId,
+              ...(isSupervisor ? teamCollaboratorIds : []),
+            ])
+          ),
+    };
+  }
+
+  private async getCollaboratorByUserId(userId: number) {
+    return this.querySingle<{
+      id: number;
+      displayName: string;
+      supervisorId: number | null;
+      supervisorName: string | null;
+    }>(
+      `SELECT c.id,
+              c.display_name AS "displayName",
+              s.id AS "supervisorId",
+              s.display_name AS "supervisorName"
+         FROM operations_collaborator c
+         LEFT JOIN operations_collaborator s
+           ON s.id = c.supervisor_collaborator_id
+        WHERE c.user_id = $1
+          AND c.deleted_at IS NULL`,
+      [userId]
+    );
+  }
+
+  private async getCollaboratorById(collaboratorId: number) {
+    const collaborator = await this.querySingle<{
+      id: number;
+      displayName: string;
+      supervisorId: number | null;
+      supervisorName: string | null;
+    }>(
+      `SELECT c.id,
+              c.display_name AS "displayName",
+              s.id AS "supervisorId",
+              s.display_name AS "supervisorName"
+         FROM operations_collaborator c
+         LEFT JOIN operations_collaborator s
+           ON s.id = c.supervisor_collaborator_id
+        WHERE c.id = $1
+          AND c.deleted_at IS NULL`,
+      [collaboratorId]
+    );
+    if (!collaborator) {
+      throw new NotFoundException('Collaborator not found.');
+    }
+    return collaborator;
+  }
+
+  private async getProjectDetails(
+    projectId: number,
+    actorCollaboratorId?: number | null
+  ) {
+    const project = await this.querySingle<{
+      id: number;
+      contractId: number | null;
+      managerCollaboratorId: number | null;
+      code: string;
+      name: string;
+      clientName: string | null;
+      summary: string | null;
+      status: string;
+      progressPercent: number | null;
+      deliveryModel: string | null;
+      budgetAmount: number | null;
+      startDate: string | null;
+      endDate: string | null;
+      contractName: string | null;
+      contractStatus: string | null;
+      contractCategory: string | null;
+      managerName: string | null;
+      myAssignmentId: number | null;
+      myRoleLabel: string | null;
+      teamSize: number;
+    }>(
+      `SELECT p.id,
+              p.contract_id AS "contractId",
+              p.manager_collaborator_id AS "managerCollaboratorId",
+              p.code,
+              p.name,
+              p.client_name AS "clientName",
+              p.summary,
+              p.status,
+              p.progress_percent AS "progressPercent",
+              p.delivery_model AS "deliveryModel",
+              p.budget_amount AS "budgetAmount",
+              p.start_date AS "startDate",
+              p.end_date AS "endDate",
+              c.name AS "contractName",
+              c.status AS "contractStatus",
+              c.contract_category AS "contractCategory",
+              m.display_name AS "managerName",
+              MAX(CASE WHEN pa.collaborator_id = $2 THEN pa.id END)::int AS "myAssignmentId",
+              MAX(CASE WHEN pa.collaborator_id = $2 THEN pa.role_label END) AS "myRoleLabel",
+              COUNT(DISTINCT pa.id)::int AS "teamSize"
+         FROM operations_project p
+         LEFT JOIN operations_contract c ON c.id = p.contract_id
+         LEFT JOIN operations_collaborator m ON m.id = p.manager_collaborator_id
+         LEFT JOIN operations_project_assignment pa
+           ON pa.project_id = p.id
+          AND pa.deleted_at IS NULL
+        WHERE p.id = $1
+          AND p.deleted_at IS NULL
+        GROUP BY p.id, c.id, m.id`,
+      [projectId, actorCollaboratorId ?? null]
+    );
+
+    if (!project) {
+      throw new NotFoundException('Project not found.');
+    }
+
+    const [assignments, relatedContract, timesheetSummary, operationalIndicators] =
+      await Promise.all([
+        this.queryRows<{
+          id: number;
+          collaboratorId: number;
+          collaboratorName: string;
+          roleLabel: string | null;
+          allocationPercent: number | null;
+          weeklyHours: number | null;
+          isBillable: boolean;
+          startDate: string | null;
+          endDate: string | null;
+          status: string;
+        }>(
+          `SELECT pa.id,
+                  pa.collaborator_id AS "collaboratorId",
+                  c.display_name AS "collaboratorName",
+                  pa.role_label AS "roleLabel",
+                  pa.allocation_percent AS "allocationPercent",
+                  pa.weekly_hours AS "weeklyHours",
+                  pa.is_billable AS "isBillable",
+                  pa.start_date AS "startDate",
+                  pa.end_date AS "endDate",
+                  pa.status
+             FROM operations_project_assignment pa
+             JOIN operations_collaborator c ON c.id = pa.collaborator_id
+            WHERE pa.project_id = $1
+              AND pa.deleted_at IS NULL
+            ORDER BY c.display_name ASC`,
+          [projectId]
+        ),
+        project.contractId
+          ? this.querySingle<{
+              id: number;
+              code: string;
+              name: string;
+              clientName: string;
+              contractCategory: string;
+              billingModel: string;
+              status: string;
+              startDate: string;
+              endDate: string | null;
+              budgetAmount: number | null;
+              monthlyHourCap: number | null;
+              description: string | null;
+              originType: string | null;
+              originId: number | null;
+            }>(
+              `SELECT id,
+                      code,
+                      name,
+                      client_name AS "clientName",
+                      contract_category AS "contractCategory",
+                      billing_model AS "billingModel",
+                      status,
+                      start_date AS "startDate",
+                      end_date AS "endDate",
+                      budget_amount AS "budgetAmount",
+                      monthly_hour_cap AS "monthlyHourCap",
+                      description,
+                      origin_type AS "originType",
+                      origin_id AS "originId"
+                 FROM operations_contract
+                WHERE id = $1
+                  AND deleted_at IS NULL`,
+              [project.contractId]
+            )
+          : Promise.resolve(null),
+        this.querySingle<{
+          totalTimesheets: string;
+          pendingTimesheets: string;
+          totalHours: string | null;
+        }>(
+          `SELECT COUNT(DISTINCT t.id)::text AS "totalTimesheets",
+                  COUNT(DISTINCT t.id) FILTER (WHERE t.status = 'submitted')::text AS "pendingTimesheets",
+                  COALESCE(SUM(e.hours), 0)::text AS "totalHours"
+             FROM operations_project_assignment pa
+             LEFT JOIN operations_timesheet_entry e
+               ON e.project_assignment_id = pa.id
+              AND e.deleted_at IS NULL
+             LEFT JOIN operations_timesheet t
+               ON t.id = e.timesheet_id
+              AND t.deleted_at IS NULL
+            WHERE pa.project_id = $1
+              AND pa.deleted_at IS NULL`,
+          [projectId]
+        ),
+        this.querySingle<{
+          activeAssignments: string;
+          billableAssignments: string;
+          averageAllocation: string | null;
+          totalWeeklyHours: string | null;
+        }>(
+          `SELECT COUNT(*) FILTER (WHERE status IN ('planned', 'active'))::text AS "activeAssignments",
+                  COUNT(*) FILTER (WHERE is_billable = true AND status IN ('planned', 'active'))::text AS "billableAssignments",
+                  COALESCE(AVG(allocation_percent), 0)::text AS "averageAllocation",
+                  COALESCE(SUM(weekly_hours), 0)::text AS "totalWeeklyHours"
+             FROM operations_project_assignment
+            WHERE project_id = $1
+              AND deleted_at IS NULL`,
+          [projectId]
+        ),
+      ]);
+
+    return {
+      ...project,
+      assignments,
+      relatedContract,
+      timesheetSummary: {
+        totalTimesheets: Number(timesheetSummary?.totalTimesheets ?? 0),
+        pendingTimesheets: Number(timesheetSummary?.pendingTimesheets ?? 0),
+        totalHours: Number(timesheetSummary?.totalHours ?? 0),
+      },
+      operationalIndicators: {
+        activeAssignments: Number(operationalIndicators?.activeAssignments ?? 0),
+        billableAssignments: Number(
+          operationalIndicators?.billableAssignments ?? 0
+        ),
+        averageAllocation: Number(
+          operationalIndicators?.averageAllocation ?? 0
+        ),
+        totalWeeklyHours: Number(operationalIndicators?.totalWeeklyHours ?? 0),
+      },
+    };
+  }
+
+  private async getCollaboratorDetails(collaboratorId: number) {
+    const collaborator = await this.querySingle<{
+      id: number;
+      userId: number;
+      code: string;
+      collaboratorType: string;
+      displayName: string;
+      department: string | null;
+      title: string | null;
+      levelLabel: string | null;
+      weeklyCapacityHours: number | null;
+      status: string;
+      joinedAt: string | null;
+      leftAt: string | null;
+      notes: string | null;
+      supervisorId: number | null;
+      supervisorName: string | null;
+      contractId: number | null;
+      contractStatus: string | null;
+      activeAssignments: number;
+    }>(
+      `SELECT c.id,
+              c.user_id AS "userId",
+              c.code,
+              c.collaborator_type AS "collaboratorType",
+              c.display_name AS "displayName",
+              c.department,
+              c.title,
+              c.level_label AS "levelLabel",
+              c.weekly_capacity_hours AS "weeklyCapacityHours",
+              c.status,
+              c.joined_at AS "joinedAt",
+              c.left_at AS "leftAt",
+              c.notes,
+              s.id AS "supervisorId",
+              s.display_name AS "supervisorName",
+              hiring_contract.id AS "contractId",
+              hiring_contract.status AS "contractStatus",
+              COUNT(DISTINCT pa.id)::int AS "activeAssignments"
+         FROM operations_collaborator c
+         LEFT JOIN operations_collaborator s
+           ON s.id = c.supervisor_collaborator_id
+         LEFT JOIN operations_project_assignment pa
+           ON pa.collaborator_id = c.id
+          AND pa.deleted_at IS NULL
+          AND pa.status IN ('planned', 'active')
+         LEFT JOIN LATERAL (
+           SELECT oc.id, oc.status
+             FROM operations_contract oc
+            WHERE oc.related_collaborator_id = c.id
+              AND oc.deleted_at IS NULL
+            ORDER BY CASE WHEN oc.origin_type = 'employee_hiring' THEN 0 ELSE 1 END,
+                     oc.created_at DESC
+            LIMIT 1
+         ) hiring_contract ON TRUE
+        WHERE c.id = $1
+          AND c.deleted_at IS NULL
+        GROUP BY c.id, s.id, hiring_contract.id, hiring_contract.status`,
+      [collaboratorId]
+    );
+
+    if (!collaborator) {
+      throw new NotFoundException('Collaborator not found.');
+    }
+
+    const [assignedProjects, relatedContracts, weeklySchedule, timesheetSummary, timeOffSummary, scheduleAdjustmentRequests] =
+      await Promise.all([
+        this.queryRows(
+          `SELECT p.id,
+                  p.code,
+                  p.name,
+                  p.status,
+                  pa.role_label AS "roleLabel",
+                  pa.allocation_percent AS "allocationPercent",
+                  pa.weekly_hours AS "weeklyHours",
+                  pa.start_date AS "startDate",
+                  pa.end_date AS "endDate"
+             FROM operations_project_assignment pa
+             JOIN operations_project p ON p.id = pa.project_id
+            WHERE pa.collaborator_id = $1
+              AND pa.deleted_at IS NULL
+              AND p.deleted_at IS NULL
+            ORDER BY p.name ASC`,
+          [collaboratorId]
+        ),
+        this.queryRows(
+          `SELECT c.id,
+                  c.code,
+                  c.name,
+                  c.contract_category AS "contractCategory",
+                  c.client_name AS "clientName",
+                  c.billing_model AS "billingModel",
+                  c.start_date AS "startDate",
+                  c.end_date AS "endDate",
+                  c.budget_amount AS "budgetAmount",
+                  c.monthly_hour_cap AS "monthlyHourCap",
+                  c.status,
+                  c.origin_type AS "originType",
+                  c.origin_id AS "originId",
+                  c.description
+             FROM operations_contract c
+            WHERE c.related_collaborator_id = $1
+              AND c.deleted_at IS NULL
+            ORDER BY c.created_at DESC`,
+          [collaboratorId]
+        ),
+        this.queryRows(
+          `SELECT weekday,
+                  is_working_day AS "isWorkingDay",
+                  start_time AS "startTime",
+                  end_time AS "endTime",
+                  break_minutes AS "breakMinutes"
+             FROM operations_collaborator_schedule_day
+            WHERE collaborator_id = $1
+              AND deleted_at IS NULL
+            ORDER BY id ASC`,
+          [collaboratorId]
+        ),
+        this.querySingle<{
+          totalTimesheets: string;
+          pendingTimesheets: string;
+          totalHours: string | null;
+        }>(
+          `SELECT COUNT(*)::text AS "totalTimesheets",
+                  COUNT(*) FILTER (WHERE status = 'submitted')::text AS "pendingTimesheets",
+                  COALESCE(SUM(total_hours), 0)::text AS "totalHours"
+             FROM operations_timesheet
+            WHERE collaborator_id = $1
+              AND deleted_at IS NULL`,
+          [collaboratorId]
+        ),
+        this.querySingle<{
+          totalRequests: string;
+          pendingRequests: string;
+          approvedRequests: string;
+        }>(
+          `SELECT COUNT(*)::text AS "totalRequests",
+                  COUNT(*) FILTER (WHERE status = 'submitted')::text AS "pendingRequests",
+                  COUNT(*) FILTER (WHERE status = 'approved')::text AS "approvedRequests"
+             FROM operations_time_off_request
+            WHERE collaborator_id = $1
+              AND deleted_at IS NULL`,
+          [collaboratorId]
+        ),
+        this.queryRows(
+          `SELECT id,
+                  request_scope AS "requestScope",
+                  effective_start_date AS "effectiveStartDate",
+                  effective_end_date AS "effectiveEndDate",
+                  status,
+                  reason
+             FROM operations_schedule_adjustment_request
+            WHERE collaborator_id = $1
+              AND deleted_at IS NULL
+            ORDER BY effective_start_date DESC, id DESC`,
+          [collaboratorId]
+        ),
+      ]);
+
+    return {
+      ...collaborator,
+      assignedProjects,
+      relatedContracts,
+      weeklySchedule,
+      timesheetSummary: {
+        totalTimesheets: Number(timesheetSummary?.totalTimesheets ?? 0),
+        pendingTimesheets: Number(timesheetSummary?.pendingTimesheets ?? 0),
+        totalHours: Number(timesheetSummary?.totalHours ?? 0),
+      },
+      timeOffSummary: {
+        totalRequests: Number(timeOffSummary?.totalRequests ?? 0),
+        pendingRequests: Number(timeOffSummary?.pendingRequests ?? 0),
+        approvedRequests: Number(timeOffSummary?.approvedRequests ?? 0),
+      },
+      scheduleAdjustmentRequests,
+    };
+  }
+
+  private async getDirectReportIds(collaboratorId: number) {
+    return (
+      await this.queryRows<{ id: number }>(
+        `SELECT id
+           FROM operations_collaborator
+          WHERE supervisor_collaborator_id = $1
+            AND deleted_at IS NULL
+          ORDER BY id ASC`,
+        [collaboratorId]
+      )
+    ).map((row) => row.id);
+  }
+
+  private async getAssignedProjectIds(collaboratorIds: number[]) {
+    if (!collaboratorIds.length) return [];
+    return (
+      await this.queryRows<{ projectId: number }>(
+        `SELECT DISTINCT project_id AS "projectId"
+           FROM operations_project_assignment
+          WHERE deleted_at IS NULL
+            AND status IN ('planned', 'active')
+            AND collaborator_id = ANY($1::int[])`,
+        [collaboratorIds]
+      )
+    ).map((row) => row.projectId);
+  }
+
+  private async getTimesheetById(timesheetId: number) {
+    const timesheet = await this.querySingle<{
+      id: number;
+      collaboratorId: number;
+      approverCollaboratorId: number | null;
+      status: string;
+    }>(
+      `SELECT id,
+              collaborator_id AS "collaboratorId",
+              approver_collaborator_id AS "approverCollaboratorId",
+              status
+         FROM operations_timesheet
+        WHERE id = $1
+          AND deleted_at IS NULL`,
+      [timesheetId]
+    );
+    if (!timesheet) {
+      throw new NotFoundException('Timesheet not found.');
+    }
+    return timesheet;
+  }
+
+  private async replaceTimesheetEntries(
+    client: any,
+    timesheetId: number,
+    entries: TimesheetEntryPayload[],
+    collaboratorId: number
+  ) {
+    await client.$executeRawUnsafe(
+      `UPDATE operations_timesheet_entry
+          SET deleted_at = NOW()
+        WHERE timesheet_id = $1
+          AND deleted_at IS NULL`,
+      timesheetId
+    );
+
+    if (!entries.length) return;
+
+    const assignmentIds = entries
+      .map((entry) => entry.projectAssignmentId)
+      .filter((value): value is number => typeof value === 'number');
+
+    if (assignmentIds.length) {
+      const assignments = (await client.$queryRawUnsafe(
+        `SELECT id, collaborator_id AS "collaboratorId"
+           FROM operations_project_assignment
+          WHERE id = ANY($1::int[])
+            AND deleted_at IS NULL`,
+        assignmentIds
+      )) as { id: number; collaboratorId: number }[];
+      const assignmentMap = new Map(
+        assignments.map((assignment) => [
+          assignment.id,
+          assignment.collaboratorId,
+        ])
+      );
+      for (const assignmentId of assignmentIds) {
+        if (assignmentMap.get(assignmentId) !== collaboratorId) {
+          throw new ForbiddenException(
+            'Timesheet entries must use assignments owned by the target collaborator.'
+          );
+        }
+      }
+    }
+
+    for (const entry of entries) {
+      await client.$executeRawUnsafe(
+        `INSERT INTO operations_timesheet_entry (
+          timesheet_id,
+          project_assignment_id,
+          activity_label,
+          work_date,
+          hours,
+          description,
+          created_at,
+          updated_at
+        ) VALUES ($1, $2, $3, $4, $5, $6, NOW(), NOW())`,
+        timesheetId,
+        entry.projectAssignmentId ?? null,
+        entry.activityLabel ?? null,
+        entry.workDate,
+        entry.hours,
+        entry.description ?? null
+      );
+    }
+  }
+
+  private async refreshTimesheetTotal(client: any, timesheetId: number) {
+    await client.$executeRawUnsafe(
+      `UPDATE operations_timesheet
+          SET total_hours = (
+                SELECT COALESCE(SUM(hours), 0)
+                  FROM operations_timesheet_entry
+                 WHERE timesheet_id = $1
+                   AND deleted_at IS NULL
+              ),
+              updated_at = NOW()
+        WHERE id = $1`,
+      timesheetId
+    );
+  }
+
+  private async upsertApproval(
+    client: any,
+    input: {
+      targetType: ApprovalTargetType;
+      targetId: number;
+      requesterCollaboratorId: number;
+      approverCollaboratorId: number | null;
+    }
+  ) {
+    const existing = (await client.$queryRawUnsafe(
+      `SELECT id
+         FROM operations_approval
+        WHERE target_type = $1
+          AND target_id = $2
+          AND deleted_at IS NULL`,
+      input.targetType,
+      input.targetId
+    )) as { id: number }[];
+
+    let approvalId = existing[0]?.id;
+    if (!approvalId) {
+      const created = (await client.$queryRawUnsafe(
+        `INSERT INTO operations_approval (
+          target_type,
+          target_id,
+          requester_collaborator_id,
+          approver_collaborator_id,
+          status,
+          submitted_at,
+          created_at,
+          updated_at
+        ) VALUES ($1, $2, $3, $4, 'pending', NOW(), NOW(), NOW())
+        RETURNING id`,
+        input.targetType,
+        input.targetId,
+        input.requesterCollaboratorId,
+        input.approverCollaboratorId
+      )) as { id: number }[];
+      approvalId = created[0]?.id;
+      await this.insertApprovalHistory(
+        client,
+        approvalId,
+        input.requesterCollaboratorId,
+        'created',
+        null
+      );
+    } else {
+      await client.$executeRawUnsafe(
+        `UPDATE operations_approval
+            SET requester_collaborator_id = $1,
+                approver_collaborator_id = $2,
+                status = 'pending',
+                submitted_at = NOW(),
+                decided_at = NULL,
+                decision_note = NULL,
+                updated_at = NOW()
+          WHERE id = $3`,
+        input.requesterCollaboratorId,
+        input.approverCollaboratorId,
+        approvalId
+      );
+      await this.insertApprovalHistory(
+        client,
+        approvalId,
+        input.requesterCollaboratorId,
+        'reopened',
+        null
+      );
+    }
+
+    await this.insertApprovalHistory(
+      client,
+      approvalId,
+      input.requesterCollaboratorId,
+      'submitted',
+      null
+    );
+  }
+
+  private async insertApprovalHistory(
+    client: any,
+    approvalId: number,
+    actorCollaboratorId: number | null,
+    action:
+      | 'created'
+      | 'submitted'
+      | 'approved'
+      | 'rejected'
+      | 'cancelled'
+      | 'reopened',
+    note: string | null
+  ) {
+    await client.$executeRawUnsafe(
+      `INSERT INTO operations_approval_history (
+        approval_id,
+        actor_collaborator_id,
+        action,
+        note,
+        created_at
+      ) VALUES ($1, $2, $3, $4, NOW())`,
+      approvalId,
+      actorCollaboratorId,
+      action,
+      note
+    );
+  }
+
+  private async assertProjectAccess(actor: ActorContext, projectId: number) {
+    if (actor.isDirector) return;
+    if (!actor.visibleProjectIds.includes(projectId)) {
+      throw new ForbiddenException('You do not have access to this project.');
+    }
+  }
+
+  private ensureCollaboratorAccess(actor: ActorContext, collaboratorId: number) {
+    if (actor.isDirector) {
+      return;
+    }
+
+    if (!actor.visibleCollaboratorIds.includes(collaboratorId)) {
+      throw new ForbiddenException(
+        'You do not have access to this collaborator.'
+      );
+    }
+  }
+
+  private async listSingleTimesheet(actor: ActorContext, timesheetId: number) {
+    const timesheets = await this.listTimesheets(actor.userId);
+    const timesheet = (timesheets as any[]).find((item) => item.id === timesheetId);
+    if (!timesheet) {
+      throw new NotFoundException('Timesheet not found.');
+    }
+    return timesheet;
+  }
+
+  private ensureDirector(actor: ActorContext) {
+    if (!actor.isDirector) {
+      throw new ForbiddenException('Director access is required.');
+    }
+  }
+
+  private ensureSupervisor(actor: ActorContext) {
+    if (!actor.isSupervisor) {
+      throw new ForbiddenException('Supervisor access is required.');
+    }
+  }
+
+  private ensureCollaborator(actor: ActorContext) {
+    if (!actor.isCollaborator) {
+      throw new ForbiddenException('Operations collaborator access is required.');
+    }
+  }
+
+  private defaultWeeklySchedule() {
+    return [
+      {
+        weekday: 'monday',
+        isWorkingDay: true,
+        startTime: '09:00',
+        endTime: '18:00',
+        breakMinutes: 60,
+      },
+      {
+        weekday: 'tuesday',
+        isWorkingDay: true,
+        startTime: '09:00',
+        endTime: '18:00',
+        breakMinutes: 60,
+      },
+      {
+        weekday: 'wednesday',
+        isWorkingDay: true,
+        startTime: '09:00',
+        endTime: '18:00',
+        breakMinutes: 60,
+      },
+      {
+        weekday: 'thursday',
+        isWorkingDay: true,
+        startTime: '09:00',
+        endTime: '18:00',
+        breakMinutes: 60,
+      },
+      {
+        weekday: 'friday',
+        isWorkingDay: true,
+        startTime: '09:00',
+        endTime: '18:00',
+        breakMinutes: 60,
+      },
+      {
+        weekday: 'saturday',
+        isWorkingDay: false,
+        startTime: null,
+        endTime: null,
+        breakMinutes: 0,
+      },
+      {
+        weekday: 'sunday',
+        isWorkingDay: false,
+        startTime: null,
+        endTime: null,
+        breakMinutes: 0,
+      },
+    ] as const;
+  }
+
+  private async replaceCollaboratorScheduleDays(
+    client: any,
+    collaboratorId: number,
+    weeklySchedule?: CollaboratorPayload['weeklySchedule']
+  ) {
+    const schedule = weeklySchedule?.length
+      ? weeklySchedule
+      : this.defaultWeeklySchedule();
+
+    await client.$executeRawUnsafe(
+      `UPDATE operations_collaborator_schedule_day
+          SET deleted_at = NOW(),
+              updated_at = NOW()
+        WHERE collaborator_id = $1
+          AND deleted_at IS NULL`,
+      collaboratorId
+    );
+
+    for (const day of schedule) {
+      await client.$executeRawUnsafe(
+        `INSERT INTO operations_collaborator_schedule_day (
+          collaborator_id,
+          weekday,
+          is_working_day,
+          start_time,
+          end_time,
+          break_minutes,
+          created_at,
+          updated_at
+        ) VALUES ($1, $2, $3, $4, $5, $6, NOW(), NOW())`,
+        collaboratorId,
+        day.weekday,
+        day.isWorkingDay ?? true,
+        day.isWorkingDay === false ? null : day.startTime ?? null,
+        day.isWorkingDay === false ? null : day.endTime ?? null,
+        day.breakMinutes ?? null
+      );
+    }
+  }
+
+  private async replaceProjectAssignments(
+    client: any,
+    projectId: number,
+    teamAssignments?: ProjectPayload['teamAssignments']
+  ) {
+    await client.$executeRawUnsafe(
+      `UPDATE operations_project_assignment
+          SET deleted_at = NOW(),
+              updated_at = NOW()
+        WHERE project_id = $1
+          AND deleted_at IS NULL`,
+      projectId
+    );
+
+    for (const assignment of teamAssignments ?? []) {
+      await client.$executeRawUnsafe(
+        `INSERT INTO operations_project_assignment (
+          project_id,
+          collaborator_id,
+          role_label,
+          allocation_percent,
+          weekly_hours,
+          is_billable,
+          start_date,
+          end_date,
+          status,
+          created_at,
+          updated_at
+        ) VALUES (
+          $1, $2, $3, $4, $5, $6, $7, $8, COALESCE($9, 'active'), NOW(), NOW()
+        )`,
+        projectId,
+        assignment.collaboratorId,
+        assignment.roleLabel ?? 'Team Member',
+        assignment.allocationPercent ?? null,
+        assignment.weeklyHours ?? null,
+        assignment.isBillable ?? true,
+        assignment.startDate ?? null,
+        assignment.endDate ?? null,
+        assignment.status ?? 'active'
+      );
+    }
+  }
+
+  private mapContractCategoryForCollaboratorType(
+    collaboratorType: NonNullable<CollaboratorPayload['collaboratorType']>
+  ) {
+    switch (collaboratorType) {
+      case 'clt':
+        return 'employee';
+      case 'pj':
+      case 'freelancer':
+        return 'contractor';
+      default:
+        return 'other';
+    }
+  }
+
+  private mapBillingModelForCollaboratorType(
+    collaboratorType: NonNullable<CollaboratorPayload['collaboratorType']>
+  ) {
+    return collaboratorType === 'freelancer'
+      ? 'time_and_material'
+      : 'monthly_retainer';
+  }
+
+  private mapContractTypeForCollaboratorType(
+    collaboratorType: NonNullable<CollaboratorPayload['collaboratorType']>
+  ) {
+    switch (collaboratorType) {
+      case 'clt':
+        return 'clt';
+      case 'pj':
+        return 'pj';
+      case 'freelancer':
+        return 'freelancer_agreement';
+      case 'intern':
+        return 'fixed_term';
+      default:
+        return 'other';
+    }
+  }
+
+  private async createHiringContractDraft(
+    client: any,
+    createdByUserId: number,
+    input: {
+      collaboratorId: number;
+      collaboratorCode: string;
+      displayName: string;
+      collaboratorType: NonNullable<CollaboratorPayload['collaboratorType']>;
+      supervisorCollaboratorId: number | null;
+      startDate: string | null;
+      weeklyCapacityHours: number | null;
+      compensationAmount: number | null;
+      description: string | null;
+    }
+  ) {
+    const contractCode = `HIR-${input.collaboratorCode}`;
+    const contractName =
+      input.collaboratorType === 'clt'
+        ? `${input.displayName} Employment Contract`
+        : `${input.displayName} Service Contract`;
+
+    await client.$executeRawUnsafe(
+      `INSERT INTO operations_contract (
+        code,
+        name,
+        contract_category,
+        contract_type,
+        client_name,
+        signature_status,
+        is_active,
+        billing_model,
+        account_manager_collaborator_id,
+        related_collaborator_id,
+        origin_type,
+        origin_id,
+        start_date,
+        end_date,
+        signed_at,
+        effective_date,
+        budget_amount,
+        monthly_hour_cap,
+        status,
+        description,
+        content_html,
+        created_by_user_id,
+        updated_by_user_id,
+        created_at,
+        updated_at
+      ) VALUES (
+        $1, $2, $3, $4, $5, 'not_started', true, $6, $7, $8, 'employee_hiring', $9, $10, NULL,
+        NULL, $10, $11, $12, 'draft', $13, NULL, $14, $14, NOW(), NOW()
+      )`,
+      contractCode,
+      contractName,
+      this.mapContractCategoryForCollaboratorType(input.collaboratorType),
+      this.mapContractTypeForCollaboratorType(input.collaboratorType),
+      input.displayName,
+      this.mapBillingModelForCollaboratorType(input.collaboratorType),
+      input.supervisorCollaboratorId,
+      input.collaboratorId,
+      input.collaboratorId,
+      input.startDate ?? new Date().toISOString().slice(0, 10),
+      input.compensationAmount ?? null,
+      input.weeklyCapacityHours
+        ? Math.round(Number(input.weeklyCapacityHours) * 4)
+        : null,
+      input.description ?? null,
+      createdByUserId
+    );
+  }
+
+  private async createProjectContractDraft(
+    client: any,
+    createdByUserId: number,
+    input: {
+      projectId: number;
+      projectCode: string;
+      projectName: string;
+      clientName: string;
+      managerCollaboratorId: number | null;
+      startDate: string | null;
+      endDate: string | null;
+      budgetAmount: number | null;
+      monthlyHourCap: number | null;
+      billingModel:
+        | 'time_and_material'
+        | 'monthly_retainer'
+        | 'fixed_price';
+      contractCode: string | null;
+      contractName: string | null;
+      description: string | null;
+    }
+  ) {
+    const created = await client.$queryRawUnsafe(
+      `INSERT INTO operations_contract (
+        code,
+        name,
+        contract_category,
+        contract_type,
+        client_name,
+        signature_status,
+        is_active,
+        billing_model,
+        account_manager_collaborator_id,
+        related_collaborator_id,
+        origin_type,
+        origin_id,
+        start_date,
+        end_date,
+        signed_at,
+        effective_date,
+        budget_amount,
+        monthly_hour_cap,
+        status,
+        description,
+        content_html,
+        created_by_user_id,
+        updated_by_user_id,
+        created_at,
+        updated_at
+      ) VALUES (
+        $1, $2, 'client', 'service_agreement', $3, 'not_started', true, $4, $5, NULL, 'client_project', $6,
+        $7, $8, NULL, $7, $9, $10, 'draft', $11, NULL, $12, $12, NOW(), NOW()
+      )
+      RETURNING id`,
+      input.contractCode ?? `PRJ-${input.projectCode}`,
+      input.contractName ?? `${input.projectName} Service Agreement`,
+      input.clientName,
+      input.billingModel,
+      input.managerCollaboratorId,
+      input.projectId,
+      input.startDate ?? new Date().toISOString().slice(0, 10),
+      input.endDate ?? null,
+      input.budgetAmount ?? null,
+      input.monthlyHourCap ?? null,
+      input.description ?? null,
+      createdByUserId
+    );
+
+    return (created as { id: number }[])[0]?.id;
+  }
+
+  private async replaceContractParties(
+    client: any,
+    contractId: number,
+    parties?: ContractPayload['parties']
+  ) {
+    await client.$executeRawUnsafe(
+      `UPDATE operations_contract_party
+          SET deleted_at = NOW(),
+              updated_at = NOW()
+        WHERE contract_id = $1
+          AND deleted_at IS NULL`,
+      contractId
+    );
+
+    for (const party of parties ?? []) {
+      await client.$executeRawUnsafe(
+        `INSERT INTO operations_contract_party (
+          contract_id,
+          party_role,
+          party_type,
+          display_name,
+          document_number,
+          email,
+          phone,
+          is_primary,
+          created_at,
+          updated_at
+        ) VALUES (
+          $1, COALESCE($2, 'other'), COALESCE($3, 'company'), $4, $5, $6, $7, COALESCE($8, false), NOW(), NOW()
+        )`,
+        contractId,
+        party.partyRole ?? 'other',
+        party.partyType ?? 'company',
+        party.displayName,
+        party.documentNumber ?? null,
+        party.email ?? null,
+        party.phone ?? null,
+        party.isPrimary ?? false
+      );
+    }
+  }
+
+  private async replaceContractSignatures(
+    client: any,
+    contractId: number,
+    signatures?: ContractPayload['signatures']
+  ) {
+    await client.$executeRawUnsafe(
+      `UPDATE operations_contract_signature
+          SET deleted_at = NOW(),
+              updated_at = NOW()
+        WHERE contract_id = $1
+          AND deleted_at IS NULL`,
+      contractId
+    );
+
+    for (const signature of signatures ?? []) {
+      await client.$executeRawUnsafe(
+        `INSERT INTO operations_contract_signature (
+          contract_id,
+          signer_name,
+          signer_role,
+          signer_email,
+          signer_status,
+          signed_at,
+          created_at,
+          updated_at
+        ) VALUES (
+          $1, $2, $3, $4, COALESCE($5, 'pending'), $6, NOW(), NOW()
+        )`,
+        contractId,
+        signature.signerName,
+        signature.signerRole ?? null,
+        signature.signerEmail ?? null,
+        signature.status ?? 'pending',
+        signature.signedAt ?? null
+      );
+    }
+  }
+
+  private async replaceContractFinancialTerms(
+    client: any,
+    contractId: number,
+    financialTerms?: ContractPayload['financialTerms']
+  ) {
+    await client.$executeRawUnsafe(
+      `UPDATE operations_contract_financial_term
+          SET deleted_at = NOW(),
+              updated_at = NOW()
+        WHERE contract_id = $1
+          AND deleted_at IS NULL`,
+      contractId
+    );
+
+    for (const term of financialTerms ?? []) {
+      await client.$executeRawUnsafe(
+        `INSERT INTO operations_contract_financial_term (
+          contract_id,
+          term_type,
+          label,
+          amount,
+          recurrence,
+          due_day,
+          notes,
+          created_at,
+          updated_at
+        ) VALUES (
+          $1, COALESCE($2, 'value'), $3, $4, COALESCE($5, 'one_time'), $6, $7, NOW(), NOW()
+        )`,
+        contractId,
+        term.termType ?? 'value',
+        term.label,
+        term.amount,
+        term.recurrence ?? 'one_time',
+        term.dueDay ?? null,
+        term.notes ?? null
+      );
+    }
+  }
+
+  private async replaceContractRevisions(
+    client: any,
+    contractId: number,
+    revisions?: ContractPayload['revisions']
+  ) {
+    await client.$executeRawUnsafe(
+      `UPDATE operations_contract_revision
+          SET deleted_at = NOW(),
+              updated_at = NOW()
+        WHERE contract_id = $1
+          AND deleted_at IS NULL`,
+      contractId
+    );
+
+    for (const revision of revisions ?? []) {
+      await client.$executeRawUnsafe(
+        `INSERT INTO operations_contract_revision (
+          contract_id,
+          revision_type,
+          title,
+          effective_date,
+          status,
+          summary,
+          created_at,
+          updated_at
+        ) VALUES (
+          $1, COALESCE($2, 'revision'), $3, $4, COALESCE($5, 'draft'), $6, NOW(), NOW()
+        )`,
+        contractId,
+        revision.revisionType ?? 'revision',
+        revision.title,
+        revision.effectiveDate ?? null,
+        revision.status ?? 'draft',
+        revision.summary ?? null
+      );
+    }
+  }
+
+  private async replaceContractPdfDocument(
+    client: any,
+    contractId: number,
+    document: NonNullable<ContractPayload['replaceUploadedPdfDocument']>
+  ) {
+    await client.$executeRawUnsafe(
+      `UPDATE operations_contract_document
+          SET is_current = false,
+              updated_at = NOW()
+        WHERE contract_id = $1
+          AND deleted_at IS NULL
+          AND document_type IN ('uploaded_pdf', 'generated_pdf')`,
+      contractId
+    );
+
+    await client.$executeRawUnsafe(
+      `INSERT INTO operations_contract_document (
+        contract_id,
+        document_type,
+        file_name,
+        mime_type,
+        file_content_base64,
+        is_current,
+        notes,
+        created_at,
+        updated_at
+      ) VALUES (
+        $1, 'uploaded_pdf', $2, $3, $4, true, $5, NOW(), NOW()
+      )`,
+      contractId,
+      document.fileName,
+      document.mimeType,
+      document.fileContentBase64,
+      document.notes ?? null
+    );
+  }
+
+  private async insertContractHistory(
+    client: any,
+    contractId: number,
+    actorUserId: number | null,
+    action: string,
+    note: string | null,
+    metadataJson?: string | null
+  ) {
+    await client.$executeRawUnsafe(
+      `INSERT INTO operations_contract_history (
+        contract_id,
+        actor_user_id,
+        action,
+        note,
+        metadata_json,
+        created_at
+      ) VALUES (
+        $1, $2, $3, $4, $5, NOW()
+      )`,
+      contractId,
+      actorUserId,
+      action,
+      note,
+      metadataJson ?? null
+    );
+  }
+
+  private requireFields(input: Record<string, unknown>, required: string[]) {
+    for (const field of required) {
+      const value = input[field];
+      if (value === undefined || value === null || value === '') {
+        throw new BadRequestException(`Field "${field}" is required.`);
+      }
+    }
+  }
+
+  private buildIdFilter(ids: number[], column: string, allowAll: boolean) {
+    if (allowAll) {
+      return { clause: '1 = 1', params: [] as unknown[] };
+    }
+    if (!ids.length) {
+      return { clause: '1 = 0', params: [] as unknown[] };
+    }
+    return {
+      clause: `${column} = ANY($1::int[])`,
+      params: [ids] as unknown[],
+    };
+  }
+
+  private uniqueNumbers(values: Array<number | null | undefined>) {
+    return [
+      ...new Set(
+        values.filter((value): value is number => typeof value === 'number')
+      ),
+    ];
+  }
+
+  private pushUpdate(
+    updates: string[],
+    params: unknown[],
+    column: string,
+    value: unknown
+  ) {
+    if (value === undefined) return;
+    params.push(value);
+    updates.push(`${column} = $${params.length}`);
+  }
+
+  private param(params: unknown[], value: unknown) {
+    params.push(value);
+    return `$${params.length}`;
+  }
+
+  private groupBy<T extends Record<string, any>>(items: T[], key: keyof T) {
+    return items.reduce<Record<string, T[]>>((accumulator, item) => {
+      const groupKey = String(item[key]);
+      accumulator[groupKey] ??= [];
+      accumulator[groupKey].push(item);
+      return accumulator;
+    }, {});
+  }
+
+  private async queryRows<T = Record<string, unknown>>(
+    sql: string,
+    params: unknown[] = []
+  ) {
+    return this.prisma.$queryRawUnsafe<T[]>(sql, ...params);
+  }
+
+  private async querySingle<T = Record<string, unknown>>(
+    sql: string,
+    params: unknown[] = []
+  ) {
+    const rows = await this.queryRows<T>(sql, params);
+    return rows[0] ?? null;
+  }
+
+  private async execute(sql: string, params: unknown[] = []) {
+    return this.prisma.$executeRawUnsafe(sql, ...params);
+  }
+}