UC 8.3.1

1. Overview

Trigger

UC_8.1.1 (Flow 4A), Stage 3 Step 3 (Blocking gate — Flow 6 / Flow 8 redirect) — when a trader's New_Level > 6, the Middleware synchronously invokes Flow 8 and blocks all remaining Stage 3 steps (Reset Balance, Update Risk, Re-Enable Trading) until Flow 8 returns a completed status.

Pre-conditions

• The trader is being promoted to New_Level > 6
• Users.compensation_track (Comp_Track) is set — either 'Standard' or 'Flex' — read as-is from the DB, never recalculated.

Post-conditions

• [If skip condition met] → no action taken.
• [US W-2, Path A] → [CHR-123] a Freshdesk ticket + Slack alert has been generated for Ops to manually update Rippling. The trader's compensation inside Rippling itself is NOT yet updated (pending manual action) — but the promotion flow itself is complete, and the trader can trade immediately.
• [International, Path B] → a one-off Dots top-up payout has been dispatched (if applicable) and user_employment_profiles.dots_monthly_retainer has been updated to the new rate.

---

Basic Flow

Step 1 — Data Lookup & Rate Selection

1. The Middleware retrieves from Table A (Forex) or Table B (Futures): Base_Income, Base_Income_Flex, and Title.

2. The Middleware reads Users.compensation_track (Comp_Track) as currently stored in the DB — this field is backend-only and can only be changed manually by HR/Operations inside Rippling; the trader can never change it via the dashboard.

3. Rate selection:

   • [If Comp_Track == 'Standard'] → New_Pay = Base_Income.
   • [If Comp_Track == 'Flex'] → New_Pay = Base_Income_Flex.
   • International contractors default to Base_Income_Flex.

4. Skip condition BR_8.3.1.1: [If New_Pay and Title for New_Level are both identical to the trader's current pay and title] → the Middleware bypasses the entire flow. No API call, no Freshdesk ticket, no Dots payout, no Slack alert is generated. s

5. [Else] → proceed to Step 2 (Path A) or Step 3 (Path B) depending on the trader's employment type (US W-2 vs. International Contractor).

   1. The Middleware queries billing_country directly from the PostgreSQL Users table to decide which path to route the trader into:
   • [If billing_country == 'US'] → Path A (US W-2)
   • [Else] → Path B (International)

---

Step 2 — Path A (US W-2)

1. [CHR-123] Since Rippling exposes no public API to update employee compensation, the Middleware fires a webhook to Zapier to generate a Freshdesk ticket and a Slack alert for the Operations team.

   Freshdesk ticket payload:

   Field	Value
   Trader_Name	Trader's full name
   User_ID	Internal user ID
   Rippling_ID	Trader's Rippling employee ID
   New_Job_Title	Title for New_Level (from Step 1.1)
   New_Compensation_Rate	New_Pay (from Step 1.3) — Hourly or Annual, per Base_Income_Type

   • [If only Title changed and New_Pay is unchanged] → the ticket still generates, but New_Compensation_Rate is set to the current (unchanged) rate — Ops only needs to update the job title in Rippling.

2. Operations uses this ticket to manually update the trader's compensation profile inside the Rippling dashboard, backdating the effective date to Today + 1 Day (calendar-day boundary — see BR_8.3.1.4).

3. UI behavior: the trading-account processing modal (triggered by Flow 4A) is not blocked by this manual Rippling update. Once the broker account for New_Level is successfully provisioned and the Freshdesk ticket has been successfully created, the modal closes and the trader can trade immediately — regardless of whether Ops has processed the Freshdesk ticket yet.

---

Step 3 — Path B (International Contractor)

1. The Middleware calls POST /calculate-prorated-raise .

2. Data retrieval:

   • Query Users table for compensation_track and Standard_Hours.
   • Query Table A/B for Base_Income, Base_Income_Flex, and Base_Income_Type using New_Level.

3. Rate selection:

   • International contractors default to Rate = Base_Income_Flex.

4. Retainer calculation:

   • [If Base_Income_Type == 'Hourly'] → New_Adjusted_Retainer = Rate * ((Standard_Hours * 52) / 12).
   • [If Base_Income_Type == 'Annual'] → New_Adjusted_Retainer = Rate / 12.

   Example (Hourly): Rate = 25 (USD/hour), Standard_Hours = 40 (hours/week) → New_Adjusted_Retainer = 25 * ((40 * 52) / 12) = 25 * (2080 / 12) = 25 * 173.33 = 4,333.33 (USD/month).

   Example (Annual): Rate = 72,000 (USD/year) → New_Adjusted_Retainer = 72,000 / 12 = 6,000 (USD/month).

5. Proration math:

   • Old value retrieval: the Middleware retrieves Old_Adjusted_Retainer and Old_Comp_Track from the values already saved at the time Flow 4A executed this promotion (the value of the trader's compensation parameters immediately before this raise) — reads user_employment_profiles.dots_monthly_retainer as it stood right before this promotion overwrote it.
   • First-time Level 6→7 case BR_8.3.1.7: no special-case branch is required — see BR_8.3.1.7.
   • Proration_Factor is calculated using Business Days Only (US/Central) — excluding both weekends (Sat/Sun) and US Federal/Bank holidays (e.g. Independence Day, Thanksgiving, Christmas), aligned to the standard US corporate banking/payroll calendar.
   • Prorated_Adjustment = (New_Adjusted_Retainer - Old_Adjusted_Retainer) * Proration_Factor — this is the delta/top-up between old and new rate for the remaining days in the current month, NOT the full remaining-days amount at the new rate.

   Example: Trader is promoted on 2026-11-18 (US/Central). November 2026 has 30 calendar days; counting Business Days Only from 11-19 to 11-30, excluding weekends and the Thanksgiving holiday (11-26, Thu) and the day after if observed as a bank holiday — assume 8 remaining business days out of a 20 business-day month → Proration_Factor = 8 / 20 = 0.4.

   Old_Adjusted_Retainer = 4,000 (snapshot at last promotion), New_Adjusted_Retainer = 4,333.33 (recalculated in Step 3.4 above) → Prorated_Adjustment = (4,333.33 - 4,000) * 0.4 = 333.33 * 0.4 = 133.33 (USD), dispatched immediately as a one-off Dots payout. Starting 2026-12-01, the monthly cron (BR_8.3.1.6) pays the full New_Adjusted_Retainer = 4,333.33.

6. Automated action:

   • Trigger a one-off Dots API payout for Prorated_Adjustment, dispatched immediately at the moment of promotion (not deferred to the 1st of next month).
   • [CHR-131] Update user_employment_profiles.dots_monthly_retainer = New_Adjusted_Retainer — this value is picked up by the monthly cron job (see BR_8.3.1.6) starting the 1st of next month.
   • Send a Slack alert to Admin: "✅ Pay raise logic triggered for Trader [User_ID]."

---

2. Business Rules

BR_8.3.1.1: Skip Condition — Identical Pay/Title

If Base_Income (or Base_Income_Flex, per the trader's Comp_Track) and Title for New_Level are mathematically identical to the trader's current pay and title, the entire Flow 8 pipeline is bypassed — no API call, no Freshdesk ticket, no Dots payout, and no operational alert is generated.

BR_8.3.1.4: Effective Date — Calendar Day, Not Rolling 24-Hour

The new pay rate's effective date is Today + 1 Day, based on the calendar day (US/Central), not a rolling 24-hour timestamp. Example: if a trader hits Level 7 at 9:30 PM on 20/9, the raise becomes effective at 00:00 (midnight) US/Central time on 21/9.

BR_8.3.1.6: Path B Recurring Retainer — Internal Cron, Not Dots-Managed Schedule

[CHR-131] Dots does not support a recurring payout schedule at the API level. Instead:

• user_employment_profiles.dots_monthly_retainer (Decimal, PostgreSQL) stores each International contractor's current monthly rate.
• An internal cron job runs on the 1st of every month, queries all users with dots_monthly_retainer > 0, and calls POST /v2/transfers individually for each user.

---

3. Payment Timing Reference

---

Changelog