# Round: Confirmation — Winner Agreement & Result Freezing

## Overview

The **CONFIRMATION** round (Round 8 in the standard 8-step flow) is the final step of the competition. It transforms live-finals scores into official, immutable results through a multi-party digital agreement process.

### Purpose

After Jury 3 completes live scoring in Round 7 (LIVE_FINAL), the platform generates a **WinnerProposal** — a ranked list of projects per category. This proposal must be ratified by the jury members who scored it, confirmed by the admin, and then **frozen** so that official results cannot be tampered with.

### Key Principles

| Principle | Implementation |
|-----------|---------------|
| **Unanimous by default** | Every jury member on the finals jury must individually approve |
| **Admin override available** | Admin can force-majority or outright select winners |
| **Immutable once frozen** | Frozen results cannot be changed — new proposal required |
| **Full audit trail** | Every approval, rejection, override, and freeze is logged |
| **Per-category** | Startups and Concepts can be confirmed independently |
| **Special awards included** | Award winners are part of the confirmation package |

### Flow Summary

```
Live Finals Complete
  │
  ▼
┌─────────────────────────────┐
│  WinnerProposal Generated   │  ← Auto-generated from scores, or admin-created
│  Status: PENDING             │
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│  Jury Approval Requests     │  ← Each jury member gets notification
│  Sent to all Jury 3 members │
└─────────────┬───────────────┘
              │
    ┌─────────┼──────────┐
    ▼         ▼          ▼
 Juror A   Juror B    Juror C     ... each reviews & votes
 APPROVE   APPROVE    REJECT
    │         │          │
    └─────────┼──────────┘
              │
              ▼
        ┌───────────┐
        │ All voted? │
        └─────┬─────┘
              │
     ┌────────┴────────┐
     ▼                 ▼
  Unanimous?      Not Unanimous
     │                 │
     ▼                 ▼
  Status:         Admin Override
  APPROVED        Decision Point
     │                 │
     ▼            ┌────┴──────┐
  Auto-freeze     │           │
  (if enabled)    ▼           ▼
              FORCE_MAJORITY  ADMIN_DECISION
              (Accept if     (Admin picks
               majority       winners
               approved)      directly)
                  │              │
                  ▼              ▼
              Status:        Status:
              OVERRIDDEN     OVERRIDDEN
                  │              │
                  └──────┬───────┘
                         ▼
                    Admin Freeze
                    (manual trigger)
                         │
                         ▼
                    Status: FROZEN
                    Results are official
```

---

## Current System

Today, there is **no confirmation step**. The pipeline flow is:

```
INTAKE → FILTER → EVALUATION → SELECTION → LIVE_FINAL → RESULTS
```

The `RESULTS` stage type simply displays computed results from LIVE_FINAL. There is:
- No jury sign-off on results
- No admin confirmation step
- No freeze/lock mechanism
- No override system for disputed results
- No multi-party agreement

**Impact:** Results can theoretically be changed at any time, there's no evidence trail of who agreed to the outcome, and no formal "cementing" of winners.

---

## Redesigned Confirmation Round

### ConfirmationConfig

```typescript
type ConfirmationConfig = {
  // ── Approval Requirements ──────────────────────────────
  requireAllJuryApproval: boolean;    // true = unanimous, false = majority
  juryGroupId: string | null;         // Which jury must approve (default: Jury 3)
  minimumApprovalThreshold?: number;  // For non-unanimous: minimum % (e.g., 0.67 = 2/3)

  // ── Admin Override ──────────────────────────────────────
  adminOverrideEnabled: boolean;      // Admin can force result
  overrideModes: OverrideMode[];      // Available override options

  // ── Freeze Behavior ─────────────────────────────────────
  autoFreezeOnApproval: boolean;      // Lock results immediately when all approve
  requireExplicitFreeze: boolean;     // Even after approval, admin must click "Freeze"

  // ── Per-category ────────────────────────────────────────
  perCategory: boolean;               // Separate proposals per STARTUP vs CONCEPT

  // ── Special Awards ──────────────────────────────────────
  includeSpecialAwards: boolean;      // Include award winners in confirmation

  // ── Deadline ────────────────────────────────────────────
  approvalDeadlineDays: number;       // Days jury has to respond (default: 7)
  reminderSchedule: number[];         // Days before deadline to remind (e.g., [3, 1])

  // ── Notification ────────────────────────────────────────
  notifyOnApproval: boolean;          // Notify admin when each juror approves
  notifyOnRejection: boolean;         // Notify admin immediately on any rejection
  notifyOnFreeze: boolean;            // Notify all parties when results frozen
};

type OverrideMode = 'FORCE_MAJORITY' | 'ADMIN_DECISION';
```

### Field Behavior Reference

| Field | Default | Description |
|-------|---------|-------------|
| `requireAllJuryApproval` | `true` | When true, ALL jury members must approve. When false, only `minimumApprovalThreshold` % needed |
| `juryGroupId` | Finals jury | Links to the JuryGroup that must confirm. Usually the same jury that scored live finals |
| `minimumApprovalThreshold` | `1.0` | Only used when `requireAllJuryApproval=false`. E.g., 0.67 = two-thirds majority |
| `adminOverrideEnabled` | `true` | Whether admin can bypass jury deadlock |
| `overrideModes` | `['FORCE_MAJORITY', 'ADMIN_DECISION']` | FORCE_MAJORITY: accept if >50% approved. ADMIN_DECISION: admin picks winners directly |
| `autoFreezeOnApproval` | `true` | When all approvals received, auto-freeze results |
| `requireExplicitFreeze` | `false` | If true, even after unanimous approval, admin must click "Freeze" to finalize |
| `perCategory` | `true` | Separate WinnerProposal per category |
| `includeSpecialAwards` | `true` | Include special award winners in confirmation package |
| `approvalDeadlineDays` | `7` | Jury has this many days to approve |
| `reminderSchedule` | `[3, 1]` | Reminder emails N days before deadline |

---

## WinnerProposal Lifecycle

### States

```typescript
enum WinnerProposalStatus {
  PENDING     = 'PENDING',     // Waiting for jury approvals
  APPROVED    = 'APPROVED',    // All required approvals received
  REJECTED    = 'REJECTED',    // Failed — needs new proposal or override
  OVERRIDDEN  = 'OVERRIDDEN',  // Admin used override power
  FROZEN      = 'FROZEN',      // Locked — official, immutable results
}
```

### State Transitions

```
                          ┌───────────────┐
                          │    PENDING     │◄──── Created from scores
                          └───────┬───────┘      or admin draft
                                  │
                    ┌─────────────┼─────────────┐
                    ▼             │             ▼
             All approved    Some rejected   Admin override
                    │             │             │
                    ▼             ▼             ▼
              ┌──────────┐ ┌──────────┐ ┌────────────┐
              │ APPROVED │ │ REJECTED │ │ OVERRIDDEN │
              └────┬─────┘ └────┬─────┘ └─────┬──────┘
                   │            │              │
                   │      Create new           │
                   │      proposal or          │
                   │      admin override       │
                   ▼                           ▼
              ┌──────────────────────────────────┐
              │            FROZEN                 │◄── Immutable
              └──────────────────────────────────┘
```

### Validity Rules

| Transition | From | To | Condition |
|------------|------|----|-----------|
| Auto-approve | PENDING | APPROVED | All required approvals received |
| Reject | PENDING | REJECTED | Any jury member rejects (if unanimous required) |
| Override: Force Majority | PENDING/REJECTED | OVERRIDDEN | Admin triggers; >50% approved |
| Override: Admin Decision | PENDING/REJECTED | OVERRIDDEN | Admin provides new rankings |
| Freeze | APPROVED/OVERRIDDEN | FROZEN | Admin triggers (or auto on approval) |
| Revoke freeze | *never* | — | Cannot unfreeze. Must create new proposal |

---

## Proposal Generation

### Automatic Generation

When the LIVE_FINAL round completes (all projects scored), the system auto-generates a WinnerProposal:

```typescript
async function generateWinnerProposal(
  competitionId: string,
  sourceRoundId: string,
  category: CompetitionCategory,
  proposedById: string  // system or admin user ID
): Promise<WinnerProposal> {
  // 1. Fetch all scored projects in this category from the live final round
  const scores = await getAggregatedScores(sourceRoundId, category);

  // 2. Rank by final score (jury weight + audience weight)
  const ranked = scores
    .sort((a, b) => b.finalScore - a.finalScore)
    .map(s => s.projectId);

  // 3. Build selection basis (evidence trail)
  const selectionBasis = {
    method: 'SCORE_RANKING',
    sourceRound: sourceRoundId,
    scoreBreakdown: scores.map(s => ({
      projectId: s.projectId,
      juryScore: s.juryScore,
      audienceScore: s.audienceScore,
      finalScore: s.finalScore,
      rank: s.rank,
    })),
    generatedAt: new Date().toISOString(),
  };

  // 4. Create proposal
  const proposal = await prisma.winnerProposal.create({
    data: {
      competitionId,
      category,
      status: 'PENDING',
      rankedProjectIds: ranked,
      selectionBasis,
      sourceRoundId,
      proposedById,
    },
  });

  // 5. Create approval records for each jury member
  const juryMembers = await getConfirmationJuryMembers(competitionId);
  await prisma.winnerApproval.createMany({
    data: juryMembers.map(member => ({
      winnerProposalId: proposal.id,
      userId: member.userId,
      role: 'JURY_MEMBER',
    })),
  });

  // 6. Send approval request notifications
  await notifyJuryForConfirmation(proposal.id, juryMembers);

  return proposal;
}
```

### Manual Proposal Creation

Admins can also create proposals manually (e.g., after an admin-decision override):

```typescript
async function createManualProposal(input: {
  competitionId: string;
  category: CompetitionCategory;
  rankedProjectIds: string[];
  justification: string;
  adminId: string;
}): Promise<WinnerProposal> {
  return prisma.winnerProposal.create({
    data: {
      competitionId: input.competitionId,
      category: input.category,
      status: 'PENDING',
      rankedProjectIds: input.rankedProjectIds,
      selectionBasis: {
        method: 'ADMIN_MANUAL',
        justification: input.justification,
        createdBy: input.adminId,
        createdAt: new Date().toISOString(),
      },
      sourceRoundId: await getLatestRoundId(input.competitionId),
      proposedById: input.adminId,
    },
  });
}
```

---

## Jury Approval Process

### Approval Flow

When a WinnerProposal is created, each jury member on the confirmation jury receives a notification:

1. **Notification** — Email + in-app alert: "Winner proposal for STARTUP category is ready for your review"
2. **Review** — Jury member opens the confirmation page, sees:
   - Ranked list of winners (1st, 2nd, 3rd...)
   - Score breakdown per project
   - Access to all submitted documents
   - Comments from other jury members (if any have responded)
3. **Decision** — Jury member clicks APPROVE or REJECT
   - If APPROVE: records timestamp, optional comment
   - If REJECT: must provide a reason (required text field)
4. **Progress tracking** — Admin can see real-time progress: "3/5 jury members approved"

### Jury Confirmation UI

```
┌──────────────────────────────────────────────────────────────────┐
│  🏆 Winner Confirmation — STARTUP Category                      │
│                                                                  │
│  Proposal Status: PENDING (2/5 approved)                        │
│  Deadline: February 22, 2026 (5 days remaining)                 │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Proposed Rankings:                                              │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  🥇 1st Place: OceanClean AI                             │   │
│  │     Final Score: 92.4 (Jury: 94.0 | Audience: 86.0)     │   │
│  │     [View Submissions]  [View Evaluations]               │   │
│  ├──────────────────────────────────────────────────────────┤   │
│  │  🥈 2nd Place: DeepReef Monitoring                       │   │
│  │     Final Score: 88.7 (Jury: 87.0 | Audience: 95.0)     │   │
│  │     [View Submissions]  [View Evaluations]               │   │
│  ├──────────────────────────────────────────────────────────┤   │
│  │  🥉 3rd Place: CoralGuard                                │   │
│  │     Final Score: 85.1 (Jury: 86.5 | Audience: 79.0)     │   │
│  │     [View Submissions]  [View Evaluations]               │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
│  Score Methodology: Jury 70% / Audience 30%                     │
│  Source: Round 7 — Live Finals (completed Feb 15, 2026)         │
│                                                                  │
│  ── Your Decision ──────────────────────────────────────────    │
│                                                                  │
│  Comments (optional for approve, required for reject):          │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
│  [ ✓ Approve Rankings ]    [ ✗ Reject — Request Revision ]      │
│                                                                  │
│  ── Other Jury Responses ───────────────────────────────────    │
│  ✓ Juror A — Approved (Feb 16)                                  │
│  ✓ Juror B — Approved (Feb 16) "Great selections"               │
│  ○ Juror C — Pending                                            │
│  ○ Juror D — Pending                                            │
│  ○ Juror E — Pending                                            │
└──────────────────────────────────────────────────────────────────┘
```

### Approval Logic

```typescript
async function processApproval(
  proposalId: string,
  userId: string,
  approved: boolean,
  comments?: string
): Promise<{ proposal: WinnerProposal; isComplete: boolean }> {
  // 1. Record the approval/rejection
  await prisma.winnerApproval.update({
    where: { winnerProposalId_userId: { winnerProposalId: proposalId, userId } },
    data: {
      approved,
      comments,
      respondedAt: new Date(),
    },
  });

  // 2. Log to audit trail
  await prisma.decisionAuditLog.create({
    data: {
      entityType: 'WINNER_PROPOSAL',
      entityId: proposalId,
      action: approved ? 'JURY_APPROVED' : 'JURY_REJECTED',
      userId,
      details: { comments },
    },
  });

  // 3. Check if all required approvals are in
  const config = await getConfirmationConfig(proposalId);
  const allApprovals = await prisma.winnerApproval.findMany({
    where: { winnerProposalId: proposalId },
  });

  const responded = allApprovals.filter(a => a.respondedAt !== null);
  const approvedCount = responded.filter(a => a.approved === true).length;
  const rejectedCount = responded.filter(a => a.approved === false).length;
  const totalRequired = allApprovals.length;

  let isComplete = false;
  let newStatus: WinnerProposalStatus | null = null;

  if (config.requireAllJuryApproval) {
    // Unanimous mode
    if (rejectedCount > 0) {
      newStatus = 'REJECTED';
      isComplete = true;
    } else if (approvedCount === totalRequired) {
      newStatus = 'APPROVED';
      isComplete = true;
    }
  } else {
    // Threshold mode
    const threshold = config.minimumApprovalThreshold ?? 0.5;
    if (responded.length === totalRequired) {
      if (approvedCount / totalRequired >= threshold) {
        newStatus = 'APPROVED';
      } else {
        newStatus = 'REJECTED';
      }
      isComplete = true;
    }
  }

  let proposal: WinnerProposal;
  if (newStatus) {
    proposal = await prisma.winnerProposal.update({
      where: { id: proposalId },
      data: { status: newStatus },
    });

    // Auto-freeze if configured and approved
    if (newStatus === 'APPROVED' && config.autoFreezeOnApproval) {
      proposal = await freezeProposal(proposalId, 'SYSTEM');
    }

    // Notify admin of completion
    await notifyAdminProposalComplete(proposalId, newStatus);
  } else {
    proposal = await prisma.winnerProposal.findUniqueOrThrow({
      where: { id: proposalId },
    });
    // Notify admin of progress
    if (config.notifyOnApproval && approved) {
      await notifyAdminApprovalProgress(proposalId, approvedCount, totalRequired);
    }
    if (config.notifyOnRejection && !approved) {
      await notifyAdminRejection(proposalId, userId, comments);
    }
  }

  return { proposal, isComplete };
}
```

---

## Admin Override System

The admin override exists for when jury consensus fails or when extraordinary circumstances require admin intervention.

### Override Modes

#### FORCE_MAJORITY

Accept the proposal if more than 50% of jury members approved, even though unanimous approval was required.

```typescript
async function overrideForceMajority(
  proposalId: string,
  adminId: string,
  reason: string
): Promise<WinnerProposal> {
  const approvals = await prisma.winnerApproval.findMany({
    where: { winnerProposalId: proposalId },
  });

  const approvedCount = approvals.filter(a => a.approved === true).length;
  const total = approvals.length;

  if (approvedCount <= total / 2) {
    throw new TRPCError({
      code: 'BAD_REQUEST',
      message: `Cannot force majority: only ${approvedCount}/${total} approved (need >50%)`,
    });
  }

  const proposal = await prisma.winnerProposal.update({
    where: { id: proposalId },
    data: {
      status: 'OVERRIDDEN',
      overrideById: adminId,
      overrideReason: reason,
      overrideAt: new Date(),
    },
  });

  await prisma.decisionAuditLog.create({
    data: {
      entityType: 'WINNER_PROPOSAL',
      entityId: proposalId,
      action: 'ADMIN_FORCE_MAJORITY',
      userId: adminId,
      details: {
        reason,
        approvedCount,
        totalJurors: total,
        rejections: approvals
          .filter(a => a.approved === false)
          .map(a => ({ userId: a.userId, comments: a.comments })),
      },
    },
  });

  return proposal;
}
```

#### ADMIN_DECISION

Admin directly selects winners, bypassing jury vote entirely. This is the nuclear option for deadlocked juries or exceptional circumstances.

```typescript
async function overrideAdminDecision(
  proposalId: string,
  adminId: string,
  newRankedProjectIds: string[],
  reason: string
): Promise<WinnerProposal> {
  // Store original rankings for audit
  const original = await prisma.winnerProposal.findUniqueOrThrow({
    where: { id: proposalId },
  });

  const proposal = await prisma.winnerProposal.update({
    where: { id: proposalId },
    data: {
      status: 'OVERRIDDEN',
      rankedProjectIds: newRankedProjectIds,
      overrideById: adminId,
      overrideReason: reason,
      overrideAt: new Date(),
      selectionBasis: {
        ...((original.selectionBasis as Record<string, unknown>) ?? {}),
        overrideHistory: {
          originalRanking: original.rankedProjectIds,
          newRanking: newRankedProjectIds,
          reason,
          overriddenBy: adminId,
          overriddenAt: new Date().toISOString(),
        },
      },
    },
  });

  await prisma.decisionAuditLog.create({
    data: {
      entityType: 'WINNER_PROPOSAL',
      entityId: proposalId,
      action: 'ADMIN_DECISION_OVERRIDE',
      userId: adminId,
      details: {
        reason,
        originalRanking: original.rankedProjectIds,
        newRanking: newRankedProjectIds,
      },
    },
  });

  return proposal;
}
```

### Admin Override UI

```
┌──────────────────────────────────────────────────────────────────┐
│  ⚠️  Override Winner Proposal — STARTUP Category                │
│                                                                  │
│  Current Status: REJECTED                                        │
│  Jury Votes: 3 Approved / 2 Rejected                            │
│                                                                  │
│  ── Override Options ───────────────────────────────────────     │
│                                                                  │
│  ○ Force Majority                                                │
│    Accept current rankings since 3/5 (60%) approved.             │
│    Rankings remain as originally proposed.                       │
│                                                                  │
│  ○ Admin Decision                                                │
│    Override rankings entirely. You will set the final order.     │
│                                                                  │
│  ── Override Reason (required) ─────────────────────────────    │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ Two jurors had scheduling conflicts and could not review  │   │
│  │ all presentations. Accepting majority recommendation.     │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
│  ⚠ This action is logged and cannot be undone.                  │
│                                                                  │
│  [ Cancel ]                     [ Apply Override ]               │
└──────────────────────────────────────────────────────────────────┘
```

### Admin Decision — Reorder UI

When ADMIN_DECISION mode is selected:

```
┌──────────────────────────────────────────────────────────────────┐
│  Admin Decision — Set Final Rankings                             │
│                                                                  │
│  Drag to reorder. This becomes the official result.             │
│                                                                  │
│  ┌────┬──────────────────────────────┬──────────┬────────────┐  │
│  │ #  │ Project                      │ Score    │ Actions    │  │
│  ├────┼──────────────────────────────┼──────────┼────────────┤  │
│  │ 1  │ ≡ OceanClean AI              │ 92.4     │ ↑ ↓       │  │
│  │ 2  │ ≡ DeepReef Monitoring        │ 88.7     │ ↑ ↓       │  │
│  │ 3  │ ≡ CoralGuard                 │ 85.1     │ ↑ ↓       │  │
│  │ 4  │ ≡ WaveEnergy Solutions       │ 82.3     │ ↑ ↓       │  │
│  │ 5  │ ≡ PlasticHarvest            │ 79.8     │ ↑ ↓       │  │
│  └────┴──────────────────────────────┴──────────┴────────────┘  │
│                                                                  │
│  Why are you overriding the score-based ranking?                │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
│  [ Cancel ]                         [ Confirm Final Rankings ]   │
└──────────────────────────────────────────────────────────────────┘
```

---

## Result Freezing

### What Freeze Does

Freezing a WinnerProposal makes it **immutable** — the official, permanent record of the competition results.

```typescript
async function freezeProposal(
  proposalId: string,
  triggeredBy: string  // userId or 'SYSTEM' for auto-freeze
): Promise<WinnerProposal> {
  const proposal = await prisma.winnerProposal.findUniqueOrThrow({
    where: { id: proposalId },
  });

  if (proposal.status !== 'APPROVED' && proposal.status !== 'OVERRIDDEN') {
    throw new TRPCError({
      code: 'BAD_REQUEST',
      message: `Cannot freeze proposal in ${proposal.status} status. Must be APPROVED or OVERRIDDEN.`,
    });
  }

  const frozen = await prisma.winnerProposal.update({
    where: { id: proposalId },
    data: {
      status: 'FROZEN',
      frozenById: triggeredBy === 'SYSTEM' ? null : triggeredBy,
      frozenAt: new Date(),
    },
  });

  // Log the freeze
  await prisma.decisionAuditLog.create({
    data: {
      entityType: 'WINNER_PROPOSAL',
      entityId: proposalId,
      action: 'RESULTS_FROZEN',
      userId: triggeredBy === 'SYSTEM' ? undefined : triggeredBy,
      details: {
        category: proposal.category,
        rankedProjectIds: proposal.rankedProjectIds,
        frozenAt: new Date().toISOString(),
        method: triggeredBy === 'SYSTEM' ? 'AUTO_FREEZE' : 'MANUAL_FREEZE',
      },
    },
  });

  // Update round status to COMPLETED
  const config = await getConfirmationConfig(proposalId);
  if (config.perCategory) {
    // Check if ALL categories are frozen before completing the round
    const allProposals = await prisma.winnerProposal.findMany({
      where: { competitionId: proposal.competitionId },
    });
    const allFrozen = allProposals.every(p => p.status === 'FROZEN');
    if (allFrozen) {
      await completeConfirmationRound(proposal.competitionId);
    }
  } else {
    await completeConfirmationRound(proposal.competitionId);
  }

  // Send freeze notifications
  await notifyResultsFrozen(proposalId);

  return frozen;
}
```

### Freeze Immutability

Once frozen, a WinnerProposal **cannot be modified**. The following are enforced:

| Operation | Allowed on FROZEN? | Alternative |
|-----------|--------------------|-------------|
| Change rankings | No | Create a new WinnerProposal |
| Change status | No | — |
| Add approvals | No | — |
| Delete proposal | No | — |
| Create new proposal | Yes | New proposal supersedes (admin must mark old as "superseded" in notes) |

### Freeze Guard Middleware

```typescript
// Applied to all mutation procedures on WinnerProposal
function assertNotFrozen(proposalId: string) {
  const proposal = await prisma.winnerProposal.findUniqueOrThrow({
    where: { id: proposalId },
  });
  if (proposal.status === 'FROZEN') {
    throw new TRPCError({
      code: 'FORBIDDEN',
      message: 'This winner proposal is frozen and cannot be modified. Create a new proposal if changes are needed.',
    });
  }
}
```

---

## Special Awards in Confirmation

When `includeSpecialAwards: true`, the confirmation round also covers special award winners.

### Special Award Winner Proposals

Each special award generates its own mini-proposal, but the confirmation process bundles them together:

```typescript
type ConfirmationPackage = {
  // Main competition winners
  mainProposals: {
    startup: WinnerProposal;
    concept: WinnerProposal;
  };

  // Special award winners
  awardProposals: {
    awardId: string;
    awardName: string;
    winnerId: string;  // project ID
    method: 'JURY_VOTE' | 'AUDIENCE_VOTE' | 'COMBINED_VOTE';
    score: number;
  }[];
};
```

### Confirmation UI with Awards

```
┌──────────────────────────────────────────────────────────────────┐
│  Winner Confirmation — Full Package                              │
│                                                                  │
│  ═══ STARTUP Category ════════════════════════════════════════   │
│  Status: APPROVED ✓  [Freeze Results]                           │
│  1st: OceanClean AI (92.4)                                      │
│  2nd: DeepReef Monitoring (88.7)                                │
│  3rd: CoralGuard (85.1)                                         │
│                                                                  │
│  ═══ CONCEPT Category ════════════════════════════════════════   │
│  Status: PENDING (4/5 approved)                                  │
│  1st: BlueTide Analytics (89.2)                                 │
│  2nd: MarineData Hub (84.6)                                     │
│  3rd: SeaWatch Network (81.3)                                   │
│                                                                  │
│  ═══ Special Awards ══════════════════════════════════════════   │
│  Innovation Award: OceanClean AI — Jury Vote (Score: 9.2)      │
│  Impact Award: BlueTide Analytics — Combined (Score: 8.8)       │
│  Community Award: SeaWatch Network — Audience Vote              │
│                                                                  │
│  ── Actions ─────────────────────────────────────────────────   │
│  [ Freeze All Approved ]  [ Override Pending ]  [ Export PDF ]  │
└──────────────────────────────────────────────────────────────────┘
```

---

## Admin Confirmation Dashboard

### Full Dashboard Layout

```
┌──────────────────────────────────────────────────────────────────┐
│  MOPC 2026 — Winner Confirmation                                 │
│  Round 8 of 8 | Status: ACTIVE                                   │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  Progress Summary                                         │  │
│  │  ┌──────────┬──────────┬──────────┬───────────────────┐  │  │
│  │  │ Category │ Status   │ Approvals│ Deadline          │  │  │
│  │  ├──────────┼──────────┼──────────┼───────────────────┤  │  │
│  │  │ STARTUP  │ APPROVED │ 5/5 ✓    │ — (complete)      │  │  │
│  │  │ CONCEPT  │ PENDING  │ 4/5      │ Feb 22 (5 days)   │  │  │
│  │  └──────────┴──────────┴──────────┴───────────────────┘  │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  Jury Approval Timeline                                   │  │
│  │                                                           │  │
│  │  Feb 15  ●────────────────────────────── Proposal sent   │  │
│  │  Feb 16  ●── Juror A approved ✓                          │  │
│  │  Feb 16  ●── Juror B approved ✓                          │  │
│  │  Feb 17  ●── Juror C approved ✓                          │  │
│  │  Feb 17  ●── Juror D approved ✓                          │  │
│  │  Feb ??  ○── Juror E — awaiting response                 │  │
│  │                                                           │  │
│  │  [Send Reminder to Juror E]                               │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  Audit Trail                                              │  │
│  │  Feb 17 14:32 — Juror D approved CONCEPT proposal        │  │
│  │  Feb 17 14:30 — Juror D approved STARTUP proposal        │  │
│  │  Feb 17 10:15 — Juror C approved CONCEPT proposal        │  │
│  │  Feb 16 09:22 — Juror B approved with comment            │  │
│  │  Feb 16 09:10 — Juror A approved both categories         │  │
│  │  Feb 15 18:00 — Proposals auto-generated from Round 7    │  │
│  │  [View Full Audit Log]                                    │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                  │
│  Actions:                                                        │
│  [ Freeze STARTUP Results ]  [ Override CONCEPT ]                │
│  [ Send Reminder ]  [ Export Results PDF ]  [ Create New Proposal]│
└──────────────────────────────────────────────────────────────────┘
```

---

## Notification Flow

### Notification Events

| Event | Recipients | Channel | Timing |
|-------|-----------|---------|--------|
| Proposal created | All confirmation jury | Email + In-app | Immediate |
| Jury member approves | Admin | In-app | Immediate |
| Jury member rejects | Admin | Email + In-app | Immediate |
| All approved (unanimous) | Admin + All jury | Email | Immediate |
| Proposal rejected (failed) | Admin | Email + In-app | Immediate |
| Admin override applied | All jury | Email | Immediate |
| Results frozen | All jury + Admin | Email + In-app | Immediate |
| Approval deadline approaching | Pending jury members | Email | Per reminderSchedule |
| Approval deadline passed | Admin | Email + In-app | Immediate |

### Notification Templates

```typescript
const CONFIRMATION_NOTIFICATIONS = {
  PROPOSAL_CREATED: {
    subject: 'MOPC 2026 — Winner Confirmation Required',
    body: `The winner proposal for {{category}} category is ready for your review.
           Please log in and confirm or reject the proposed rankings by {{deadline}}.

           Proposed Winners:
           {{#each rankedProjects}}
             {{rank}}. {{name}} (Score: {{score}})
           {{/each}}`,
  },

  APPROVAL_RECEIVED: {
    subject: 'MOPC 2026 — Confirmation Progress Update',
    body: `{{jurorName}} has {{approved ? "approved" : "rejected"}} the {{category}} proposal.
           Progress: {{approvedCount}}/{{totalJurors}} approved.
           {{#if comments}}Comment: "{{comments}}"{{/if}}`,
  },

  RESULTS_FROZEN: {
    subject: 'MOPC 2026 — Official Results Confirmed',
    body: `The {{category}} category results have been officially confirmed and frozen.

           Official Winners:
           {{#each rankedProjects}}
             {{rank}}. {{name}}
           {{/each}}

           These results are now immutable and represent the official outcome.`,
  },

  DEADLINE_REMINDER: {
    subject: 'MOPC 2026 — Confirmation Deadline in {{daysRemaining}} days',
    body: `You have not yet responded to the {{category}} winner proposal.
           Please review and respond by {{deadline}}.

           [Review Proposal →]`,
  },
};
```

---

## API Changes

### New tRPC Procedures

```typescript
// src/server/routers/winner-confirmation.ts

export const winnerConfirmationRouter = router({
  // ── Proposals ──────────────────────────────────────────

  /** Generate proposals from live final scores */
  generateProposals: adminProcedure
    .input(z.object({
      competitionId: z.string(),
      sourceRoundId: z.string(),
    }))
    .mutation(async ({ input, ctx }) => { ... }),

  /** Create manual proposal (admin override scenario) */
  createManualProposal: adminProcedure
    .input(z.object({
      competitionId: z.string(),
      category: z.enum(['STARTUP', 'BUSINESS_CONCEPT']),
      rankedProjectIds: z.array(z.string()).min(1),
      justification: z.string().min(10),
    }))
    .mutation(async ({ input, ctx }) => { ... }),

  /** Get proposal with approvals */
  getProposal: protectedProcedure
    .input(z.object({ proposalId: z.string() }))
    .query(async ({ input }) => { ... }),

  /** List all proposals for a competition */
  listProposals: protectedProcedure
    .input(z.object({ competitionId: z.string() }))
    .query(async ({ input }) => { ... }),

  /** Get the full confirmation package (main + awards) */
  getConfirmationPackage: adminProcedure
    .input(z.object({ competitionId: z.string() }))
    .query(async ({ input }) => { ... }),

  // ── Approvals ──────────────────────────────────────────

  /** Jury member approves or rejects */
  submitApproval: juryProcedure
    .input(z.object({
      proposalId: z.string(),
      approved: z.boolean(),
      comments: z.string().optional(),
    }))
    .mutation(async ({ input, ctx }) => { ... }),

  /** Get my pending approvals */
  getMyPendingApprovals: juryProcedure
    .query(async ({ ctx }) => { ... }),

  /** Get approval progress for a proposal */
  getApprovalProgress: protectedProcedure
    .input(z.object({ proposalId: z.string() }))
    .query(async ({ input }) => { ... }),

  // ── Admin Overrides ────────────────────────────────────

  /** Force majority acceptance */
  overrideForceMajority: adminProcedure
    .input(z.object({
      proposalId: z.string(),
      reason: z.string().min(10),
    }))
    .mutation(async ({ input, ctx }) => { ... }),

  /** Admin directly sets winners */
  overrideAdminDecision: adminProcedure
    .input(z.object({
      proposalId: z.string(),
      newRankedProjectIds: z.array(z.string()).min(1),
      reason: z.string().min(10),
    }))
    .mutation(async ({ input, ctx }) => { ... }),

  // ── Freeze ─────────────────────────────────────────────

  /** Freeze a proposal (make results official) */
  freezeProposal: adminProcedure
    .input(z.object({ proposalId: z.string() }))
    .mutation(async ({ input, ctx }) => { ... }),

  /** Freeze all approved proposals at once */
  freezeAll: adminProcedure
    .input(z.object({ competitionId: z.string() }))
    .mutation(async ({ input, ctx }) => { ... }),

  // ── Notifications ──────────────────────────────────────

  /** Send reminder to pending jury members */
  sendReminder: adminProcedure
    .input(z.object({
      proposalId: z.string(),
      userIds: z.array(z.string()).optional(), // specific jurors, or all pending
    }))
    .mutation(async ({ input }) => { ... }),

  // ── Export ─────────────────────────────────────────────

  /** Export results as PDF */
  exportResultsPdf: adminProcedure
    .input(z.object({ competitionId: z.string() }))
    .mutation(async ({ input }) => { ... }),

  /** Export results as structured JSON */
  exportResultsJson: adminProcedure
    .input(z.object({ competitionId: z.string() }))
    .query(async ({ input }) => { ... }),
});
```

---

## Service Functions

### winner-confirmation.ts

```typescript
// src/server/services/winner-confirmation.ts

/** Generate proposals for all categories from live final scores */
export async function generateProposalsFromScores(
  competitionId: string,
  sourceRoundId: string,
  triggeredBy: string
): Promise<WinnerProposal[]>;

/** Create a manual proposal with admin-specified rankings */
export async function createManualProposal(
  competitionId: string,
  category: CompetitionCategory,
  rankedProjectIds: string[],
  justification: string,
  adminId: string
): Promise<WinnerProposal>;

/** Process a jury member's approval/rejection */
export async function processApproval(
  proposalId: string,
  userId: string,
  approved: boolean,
  comments?: string
): Promise<{ proposal: WinnerProposal; isComplete: boolean }>;

/** Override with force-majority rule */
export async function overrideForceMajority(
  proposalId: string,
  adminId: string,
  reason: string
): Promise<WinnerProposal>;

/** Override with admin-selected rankings */
export async function overrideAdminDecision(
  proposalId: string,
  adminId: string,
  newRankedProjectIds: string[],
  reason: string
): Promise<WinnerProposal>;

/** Freeze a proposal — makes results immutable */
export async function freezeProposal(
  proposalId: string,
  triggeredBy: string
): Promise<WinnerProposal>;

/** Freeze all approved/overridden proposals for a competition */
export async function freezeAllApproved(
  competitionId: string,
  adminId: string
): Promise<WinnerProposal[]>;

/** Get the full confirmation package (main winners + special awards) */
export async function getConfirmationPackage(
  competitionId: string
): Promise<ConfirmationPackage>;

/** Check if all categories are frozen for a competition */
export async function isFullyFrozen(
  competitionId: string
): Promise<boolean>;

/** Send reminder notifications to pending jury members */
export async function sendApprovalReminder(
  proposalId: string,
  specificUserIds?: string[]
): Promise<void>;

/** Get aggregated scores from the source round */
export async function getAggregatedScores(
  roundId: string,
  category: CompetitionCategory
): Promise<AggregatedScore[]>;

/** Export frozen results as a structured document */
export async function exportResults(
  competitionId: string,
  format: 'json' | 'pdf'
): Promise<Buffer | Record<string, unknown>>;
```

---

## Edge Cases

| Scenario | Handling |
|----------|----------|
| **Jury member doesn't respond by deadline** | Admin notified. Can send reminders or use override |
| **All jurors reject** | Status = REJECTED. Admin must override or create new proposal |
| **Juror tries to change vote after submitting** | Not allowed. Must contact admin to reset vote |
| **Admin resets a juror's vote** | Audit logged. Juror re-notified to vote again |
| **Tie in live finals scores** | Proposal lists tied projects at same rank. Admin resolves via override |
| **Proposal frozen, then error discovered** | Cannot unfreeze. Admin creates new proposal with explanation |
| **Juror is on multiple categories** | Separate approval records per proposal (per-category) |
| **Competition has no special awards** | `includeSpecialAwards` is false; only main proposals |
| **Admin freezes before all categories confirmed** | Allowed — each category freezes independently |
| **Network failure during approval** | Optimistic UI with retry. Server-side idempotency via unique constraint |
| **Juror removed from jury group after proposal sent** | Approval record remains but marked as N/A. Threshold recalculated |
| **Multiple proposals for same category** | Only latest non-frozen proposal is active. Previous ones archived |
| **Live finals not yet complete** | Cannot generate proposal — round must be in COMPLETED status |
| **Admin tries to freeze PENDING proposal** | Blocked — must be APPROVED or OVERRIDDEN first |

---

## Integration Points

### Inbound (from other rounds/systems)

| Source | Data | Purpose |
|--------|------|---------|
| Round 7 (LIVE_FINAL) | Aggregated scores, rankings | Auto-generate WinnerProposal |
| JuryGroup (Jury 3) | Member list | Determine who must approve |
| SpecialAward system | Award winners | Include in confirmation package |
| Competition settings | Category config | Per-category proposals |

### Outbound (to other systems)

| Target | Data | Purpose |
|--------|------|---------|
| DecisionAuditLog | All actions | Full audit trail |
| Notification system | Events | Email + in-app alerts |
| Export service | Frozen results | PDF/JSON export for records |
| Admin dashboard | Progress metrics | Real-time status display |
| Competition status | COMPLETED flag | Mark competition as finished |

### Confirmation → Competition Completion

When all proposals are frozen:

```typescript
async function completeConfirmationRound(competitionId: string): Promise<void> {
  // 1. Mark the confirmation round as COMPLETED
  const confirmationRound = await prisma.round.findFirst({
    where: { competitionId, roundType: 'CONFIRMATION' },
  });

  if (confirmationRound) {
    await prisma.round.update({
      where: { id: confirmationRound.id },
      data: { status: 'ROUND_COMPLETED' },
    });
  }

  // 2. Update competition status
  await prisma.competition.update({
    where: { id: competitionId },
    data: { status: 'CLOSED' },
  });

  // 3. Log competition completion
  await prisma.decisionAuditLog.create({
    data: {
      entityType: 'COMPETITION',
      entityId: competitionId,
      action: 'COMPETITION_COMPLETED',
      details: {
        completedAt: new Date().toISOString(),
        reason: 'All winner proposals frozen',
      },
    },
  });

  // 4. Send competition-complete notifications
  await notifyCompetitionComplete(competitionId);
}
```

---

## Security Considerations

| Concern | Mitigation |
|---------|------------|
| **Jury member votes for wrong proposal** | Proposals are category-specific; UI shows only relevant proposal |
| **Admin forges jury approvals** | Approvals tied to authenticated session; audit log captures userId |
| **Results tampered after freeze** | FROZEN status enforced at database level; no UPDATE allowed |
| **Unauthorized freeze** | Only SUPER_ADMIN and PROGRAM_ADMIN can freeze (adminProcedure) |
| **Replay attack on approval** | Unique constraint on [winnerProposalId, userId] prevents double-voting |
| **Override without justification** | `reason` field is required (min 10 chars) on all overrides |
| **PDF export tampering** | Export includes cryptographic hash of frozen proposal data |

---

## Results Export Format

### JSON Export

```typescript
type ExportedResults = {
  competition: {
    id: string;
    name: string;
    programYear: number;
  };
  exportedAt: string;
  exportedBy: string;

  categories: {
    category: string;
    proposalId: string;
    status: WinnerProposalStatus;
    frozenAt: string;

    winners: {
      rank: number;
      project: {
        id: string;
        name: string;
        teamName: string;
        category: string;
      };
      scores: {
        juryScore: number;
        audienceScore: number;
        finalScore: number;
      };
    }[];

    approvals: {
      jurorName: string;
      approved: boolean;
      respondedAt: string;
      comments?: string;
    }[];

    override?: {
      type: string;
      reason: string;
      overriddenBy: string;
      overriddenAt: string;
    };
  }[];

  specialAwards: {
    awardName: string;
    winnerProject: string;
    method: string;
    score: number;
  }[];

  // Integrity hash
  integrityHash: string;
};
```

### PDF Export Structure

The PDF export contains:
1. **Cover page** — Competition name, year, date of confirmation
2. **Main winners** — Per category: ranked list with scores, team info
3. **Special awards** — Award name, winner, scoring method
4. **Jury confirmations** — List of all approvals with timestamps
5. **Override record** — If any override was used, full details
6. **Audit summary** — Key events from the audit trail
7. **Integrity hash** — SHA-256 of all frozen proposal data