SRS: UC_9.2 — Flow 13: Time-Off Management (W-2 DTO & International Hiatus)

UC Index

<a id="UC_9.2"></a>

UC_9.2 — Flow 13: Time-Off Management (W-2 DTO & International Hiatus)

1. Overview

2. Trigger

Two entry channels — the channel determines the path (CR-20261027-001):

(Source: CR-20261027-001 — client: "W2 traders can use Rippling" · "Create a very simple request form on the unified Dashboard for international contractors"; QnA [HR-DEF-01] 2026-08-15)

2.1 Path A trigger — Rippling Time Off Request Approved webhook

• Rippling owns the W-2 request, DTO balance and manager approval. Flow 13 starts only after Rippling has approved the request.
• On webhook receipt the Zap only validates and stores the request. The leave actions (Steps A-3 → A-4) run on the leave_start_date registered in Rippling, via a Zapier delay_until — the same mechanism the Return Protocol uses for the end date.
• The same webhook also triggers Flow 35 — PTO Ledger Sync (UC_9.12). Flow 13 Path A and Flow 35 run independently on the same event.
• Fields consumed from the payload: Rippling worker → user_id; Rippling Request ID; leave start date; leave end date (→ DTO_Hiatus_End_Date); approved days (→ Requested_Days).

2.2 Path B trigger — Dashboard "Request Time Off" form (International Contractor only)

UI Entry Point (UC_4.16.2 — Career & HR Widget):

• Button: "Request Time Off" — top-right of the Employment Status section within the Career & HR Widget.
• Visibility condition: International Contractor with Current_Level >= 6 only. Hidden for W-2 traders (Employment_Type = 'W-2') and for traders below Level 6.
• Design: References/Wireframe/Dashboard/Flow 13_Request Time Off modal (International).jpg · Figma — Request Time Off modal.

Modal "Request Time Off" (approved design):

Figma: Request Time Off modal

⚠️ Note: add a Cancel button to the design (currently only Send). Other closing behaviour (X / click outside / Esc) — see Q-4.

Form tool: Native Dashboard form — NOT a third-party tool (e.g. Typeform or Google Forms).

Webhook payload dispatched to Zapier Flow 13 on Send:

Trigger type: Form submission → JSON webhook → Zapier catch-hook endpoint → Flow 13.

2.3 Entry gate (both channels)

Current_Level >= 6 — checked when the Rippling webhook (Path A) or the form submission (Path B) is received.

• If Current_Level < 6 → reject / ignore. No further processing. Path A: log to BPS_Audit_Log (see Exc-1).

Reason: Level 6 is the minimum threshold for a W-2 employment contract (USA) or a retainer-based independent contractor agreement (International). Traders below Level 6 operate on an on-demand bonus model and are not eligible for this policy. (Source: Zapier Integration V7.pdf §Flow 13 lines 1949–1951; client confirmed 2026-08-22)

3. Path Router

The path is determined by the trigger channel:

Guard (consistency check): KYC-verified country (takes precedence over billing_country per CR-20260812-005) and Employment_Type must match the channel:

• Rippling webhook for a trader who is not Employment_Type = 'W-2' → do not process; log to BPS_Audit_Log (Exc-1).
• Dashboard form submitted by a W-2 trader (button should be hidden — defence in depth) → reject; no state change.

(Source: CR-20261027-001; Zapier Integration V7.pdf §Flow 13 — "Path Router" line 1951)

4. Basic Flow

Path A — USA W-2 Paid DTO

Step A-1. Receive Rippling Approval Webhook

• Zapier receives the Rippling Time Off Request Approved webhook (§2.1).
• Resolve the Rippling worker to user_id; apply the entry gate (Current_Level >= 6) and the W-2 guard (§3). Fail → Exc-1.
• Dedup on Rippling Request ID — a redelivered webhook must not extend stagnation_deadline twice.
• No DTO Balance Check and no Rippling API call by Stack Trading. Rippling owns the DTO balance and approval; Flow 13 only acts on approved requests. Requested_Days = approved days from the payload.

(Source: QnA_STAGE2_SETTINGS_CAREER_VIRAL.md [HR-DEF-01] — PTO request, balance and approval owned by Rippling)

Step A-1.5. Wait Until the Leave Start Date

• Today < leave_start_date: the Zap pauses with delay_until = leave_start_date (from the Rippling payload) and continues with Step A-3 on that date. Until then the trader trades normally; trader_status is not changed.
• Today ≥ leave_start_date: continue immediately — late webhooks are handled by Exc-2 (Case 1 / Case 2).
• Step A-2 (Flow 35 ledger) and Step A-5 (DTO_Approval_Notice) are not delayed — they run on webhook receipt.

Step A-2. PTO Ledger Sync (Flow 35 — parallel, not part of this Zap)

• The same Rippling webhook triggers Flow 35 (UC_9.12), which calls POST /api/ledger/record with metric_category = "Corporate Benefits", metric_value = "[Days_Approved] Days PTO Approved (Paid Time Off)", receipt_hash = [Rippling Request ID].

(Source: Zapier Integration V7.pdf §Flow 35 lines 2535–2548)

Step A-3. Extend Stagnation Deadline

• Execute SQL update:

  UPDATE Users
  SET stagnation_deadline = stagnation_deadline + INTERVAL '[Requested_Days] days'
  WHERE user_id = [trader_id];

• This ensures Flow 12 (Zombie Protocol) and Flow 19 (Stagnation Monitor) do not penalise the trader for inactivity during the approved leave period.

(Source: Zapier Integration V7.pdf §Flow 13 line 1961)

Step A-3.5. Close All Open Positions

Before locking the account, Middleware closes all of the trader's open orders / positions. The account lock in Step A-4 executes only after the account has no open positions.

(Source: Zapier Integration V7.pdf §Flow 13 — "Disable Trading Account via Middleware (Lock)")

Step A-4. Lock Trading Account

• Call POST /system/set-account-state:

  { "user_id": "[trader_id]", "state": "Locked", "context": "DTO" }

• Middleware sends platform-specific lock commands after confirming the account is flat (Step A-3.5):
  • Rithmic: R|API+ Suspend Trading.
  • MT5: YourBourse Contest Stop Out Plugin API (POST) — sets account to Read-Only; freezes Target Profit / Stop Loss values in RAM.
  • TraderEvolution: Admin API — sets account to Lock/Read-Only.
• Post-gateway DB writes (executed only after receiving HTTP 200 from all active gateways):
  • trader_status = 'On_Leave'
  • is_professional = TRUE (if trader is on DMA)
  • stagnation_deadline already updated in Step A-3

(Source: Zapier Integration V7.pdf §Flow 13 line 1961; §POST /system/set-account-state lines 136–140; Supplement §3.2)

Step A-5. Notify Trader

• Sent on webhook receipt (not delayed by Step A-1.5). Send DTO_Approval_Notice email via AWS SES confirming leave approval, start date, and expected return date.
• Discord notification: Push a leave-status notification into the Redis memory queue. Zapier/Bot batches messages from the queue (max 5 messages / 5 seconds) before dispatching to Discord to avoid rate-limit violations.

(Source: Zapier Integration V7.pdf §Flow 13 line 1963; Supplement §3.4)

Path B — International Contractor Unpaid Hiatus

Step B-1. Validation

• No DTO day limit applies. Proceed immediately without a balance check.

(Source: Zapier Integration V7.pdf §Flow 13 line 1965)

Step B-2. Suspend Dots Retainer

• The monthly retainer for International Contractors is managed by a Middleware cron job (Node.js, runs monthly) that calls the Dots payout API. It is NOT a Zapier step and cannot be paused via Zapier.
• Dots API itself does not have a native "suspend retainer" endpoint — Dots only handles individual payout requests on demand.
• Mechanism: Middleware sets a DB flag (e.g. is_retainer_paused = TRUE) on the trader's Users record. The monthly retainer cron checks this flag before calling Dots POST /payees and skips any record where the flag is set.
• The exact field name is an implementation decision for dev; the business requirement is: no retainer payment is dispatched to Dots while the trader is on hiatus.
• On return (Step R-3), Middleware clears the flag (is_retainer_paused = FALSE) to resume normal monthly payments.

(Source: Zapier Integration V7.pdf §Flow 13 lines 1966–1968; §Flow 6 line 1635 — "Update the recurring backend trigger for the new Dots monthly retainer"; client confirmed 2026-08-21)

Step B-3. Extend Stagnation Deadline

• Same SQL update as Path A Step A-3: extend stagnation_deadline by Requested_Days.

(Source: Zapier Integration V7.pdf §Flow 13 line 1969)

Step B-3.5. Close All Open Positions

• Same as Path A Step A-3.5: close all open orders / positions.
• Account lock in Step B-4 executes only after the account has no open positions.

(Source: Zapier Integration V7.pdf §Flow 13 — "Disable Trading Account via Middleware (Lock)")

Step B-4. Lock Trading Account

• Call POST /system/set-account-state:

  { "user_id": "[trader_id]", "state": "Locked", "context": "Hiatus" }

• Middleware sends platform-specific lock commands after confirming the account is flat (Step B-3.5):
  • Rithmic: R|API+ Suspend Trading.
  • MT5: YourBourse Contest Stop Out Plugin API (POST) — sets account to Read-Only; freezes Target Profit / Stop Loss in RAM.
  • TraderEvolution: Admin API — sets account to Lock/Read-Only.
• Post-gateway DB writes (after HTTP 200 from all active gateways):
  • trader_status = 'On_Leave'
  • is_professional = TRUE (if trader is on DMA)
  • stagnation_deadline already updated in Step B-3

(Source: Zapier Integration V7.pdf §Flow 13 line 1970; Supplement §3.2)

Step B-5. Notify Trader

• Send DTO_Approval_Notice email via AWS SES.
• Discord notification: Push leave-status notification into the Redis memory queue. Zapier/Bot batches (max 5 messages / 5 seconds) before dispatching to Discord.

(Source: Zapier Integration V7.pdf §Flow 13 line 1972; Supplement §3.4)

Return Protocol (Applies to Both Paths)

Trigger: The original Flow 13 Zap (the same Zap that processed the leave approval) resumes execution via a Zapier delay_until action set to the DTO/Hiatus End Date — Path A: leave end date from the Rippling webhook payload; Path B: End Date from the Dashboard form. This is NOT a separate backend cron job — the Zap pauses mid-execution at the point of leave approval and automatically resumes on the specified end date.

(Source: Zapier Integration V7.pdf §Flow 13; client confirmed 2026-08-22)

Ownership model:

• Zapier owns: the delay_until timer, flow control and step sequencing after resumption, the flag/database check logic, and routing the DTO_Welcome_Back notification.
• Middleware owns: Safety Check execution (queries PostgreSQL Users and blacklist), calling POST /system/set-account-state on a clean pass, pushing the Restore Trading command directly to broker servers (Rithmic / MT5 / TraderEvolution), and resuming the Dots retainer trigger (Path B).

Step R-1. Safety Check

• Middleware queries PostgreSQL for user_id. Compliance_Flagged is not a stored field — it is evaluated from existing data:
  • IF any of the following is true:
    1. The user's email has a matching row in the blacklist table (blacklist.email = Users.email AND blacklist.is_active = TRUE — same check as UC_2.6.2 Blacklist Check);
    2. Users.status ∈ {Banned_Chargeback, Failed, Terminated};
    3. Users.payout_status ≠ 'Approved' (e.g. Hold / Flagged set by BPS Apply Payout Hold, a Dots payout-profile webhook, or a Flow 14 Live trader dispute hold).
    • HALT all re-enablement. Do NOT unlock trading account. Do NOT resume payments.
    • Send immediate Slack alert to Head of Ops for manual review.
    • Terminate flow.
  • ELSE: Proceed to Step R-2.

(Source: Zapier Integration V7.pdf §Flow 13 lines 1974–1977; client confirmed 2026-08-22; QnA_BACKGROUND_MECHANISMS_CRON.md [BG-005] [BG-006] [BG-007] — client sheet 2026-11-04; blacklist schema per UC_2.6.2 / CHR-17)

Step R-2. Re-enable Trading Account

• Middleware calls POST /system/set-account-state:

  { "user_id": "[trader_id]", "state": "Active", "context": "DTO_Return" }

• Middleware reads the trader's current Current_Level from PostgreSQL at this moment (not the level at the time of leave approval — demotion during leave is reflected here).
• Middleware then pushes the Restore Trading command to the broker execution platform with risk parameters matching the trader's current level: Rithmic 'Enable Trading' / MT5 'Enable' / TraderEvolution equivalent — including the correct Notional, Daily Loss Limit, and Level Stop for Current_Level at return.

(Source: Zapier Integration V7.pdf §Flow 13 line 1978; client confirmed 2026-08-22, 2026-09-09)

Step R-3. Resume Retainer (Path B only)

• Middleware resumes the scheduled recurring Dots payout retainer trigger (clears is_retainer_paused = FALSE).
• Flow 36 (Retainer Execution — Ledger Sync) fires on the next retainer payment cycle and logs the immutable ledger entry.
• If the trader was demoted during leave: the retainer resumes at the retainer rate corresponding to their current (lower) Current_Level, not the level at leave approval.

(Source: Zapier Integration V7.pdf §Flow 13 line 1980; client confirmed 2026-08-22, 2026-09-09)

Step R-4. Notify Trader

• Send DTO_Welcome_Back email via AWS SES.

(Source: Zapier Integration V7.pdf §Flow 13 line 1982)

4.1 Special Case: Pod Leader & Founding Mentor Handling (Level 7+)

This section governs all special-case behaviors that apply exclusively when the Trader has is_pod_leader = TRUE or role_flag = 'Founding_Mentor'.

4.1.1 Failsafe Anti-Termination Gate

Before executing any leave action (Steps A-1/B-1), Middleware MUST check role flags:

IF users.is_pod_leader = TRUE OR users.role_flag = 'Founding_Mentor':
  → MUST block: do NOT fire POD_LEADER_TERMINATED webhook
  → MUST NOT invoke Flow 15C (offboarding cascade)
  → Proceed with leave processing (soft-lock, stagnation extension, etc.)
ELSE:
  → Standard Trader flow

Blocked actions during leave (applies to both triggers):

• POD_LEADER_TERMINATED webhook: never fired
• Flow 15C (Pod dissolution, carry forfeiture, Discord/Workspace offboarding): never invoked
• Pending_Carry_Balance zeroing: never executed
• Google Workspace deletion/suspension: never triggered
• Discord channel archival / Role revocation: never triggered

(Source: QnA_STAGE6_POD_SYSTEM_FLOW10_11.md [POD-XF-15] — client confirmed 2026-10-30: approved leave is temporary time off, NOT Drawdown Defense (Flow 4B) or Termination (Flow 15C))

4.1.2 Resources Preserved During On_Leave

Note on Founding Mentors: per BR_9.2.19 and the Defense Bypass rule, their trading account IS locked during On_Leave — the Founding Mentor exception covers Administrative Roles only (Pod/Discord), not the trading account lock.

(Source: QnA_STAGE6_POD_SYSTEM_FLOW10_11.md [POD-XF-15], [POD-XF-16] — client confirmed 2026-10-30; RFQ_ Stack Trading Prop Tech V7.pdf §Founding Mentor Defense Bypass)

4.1.3 Carry Balance Behavior

Pending_Carry_Balance continues to accrue and vest normally during approved leave. The monthly vest run (Flow 17, 1st of month) MUST include Pod Leaders in Pod_Leader_Registry.Status = 'On_Leave' — no freeze, no skip. Applies equally to regular Pod Leaders and Founding Mentors. Carry is only frozen or forfeited on Drawdown Defense suspension or Termination (Flow 15C).

Other payments during leave: W-2 base salary (Path A) continues via Rippling payroll; International retainer (Path B) is suspended (Step B-2) and resumed at R-3; trading performance payouts (Flow 5) earned before the leave are processed normally — no new target can be hit while the account is locked.

(Source: QnA_BACKGROUND_MECHANISMS_CRON.md [BG-008] [BG-009]; QnA_STAGE6_POD_SYSTEM_FLOW10_11.md [POD-XF-18] — client sheet 2026-11-04)

4.1.4 Pod_Leader_Registry Status During Leave

• At Step A-4 / B-4 (after gateway lock succeeds), Middleware sets Pod_Leader_Registry.Status = 'On_Leave' for the leader.
• Flow 10 matching only selects Status == 'Active' [POD-JOIN-19] → a leader in On_Leave is automatically excluded from new mentee matching. This does NOT trigger the Flow 15A Suspended pod-dissolution logic.
• At Return Protocol Step R-2 (on successful re-enable), Middleware sets Pod_Leader_Registry.Status = 'Active'.

(Source: QnA_STAGE6_POD_SYSTEM_FLOW10_11.md [POD-XF-16] — client confirmed 2026-10-30)

4.1.5 Pod SLAs During Leave

Pod SLA timers are paused while the leader is on leave — no Acting Cover, no mentee re-match:

• Flow 10.2 SLA Enforcement cron excludes users in Inactive_Hold (Flow 12) or Locked via DTO/Hiatus (Flow 13) [POD-SLA-08].
• Flow 10.5 Daily Engagement Audit excludes leaders Locked via DTO/Hiatus [POD-AUDIT-10].
• Flow 10.1B Calendar Compliance Auditor: leaders on DTO/Hiatus are exempt [POD-DISP-08].

(Source: QnA_STAGE6_POD_SYSTEM_FLOW10_11.md [POD-XF-17] — client confirmed 2026-10-30)

5. Pre-conditions

6. Post-conditions

7. Alternative Flows

Alt-1 — DTO balance exhausted (Path A):

• Handled entirely inside Rippling (Rippling policy configured by Ops per DTO_Days, Table A/B). A rejected request never produces a Time Off Request Approved webhook — Flow 13 is not triggered. See Q-1.

Alt-3 — Second time-off approved in Rippling while trader is already on leave (Path A):

• Each additional Rippling approval webhook (new Rippling Request ID) extends stagnation_deadline further by the newly approved days and updates DTO_Hiatus_End_Date.
• Re-calling POST /system/set-account-state with state = "Locked" is idempotent — account is already locked, no nested flags or duplicate lock created.
• Quota enforcement is Rippling's responsibility (no balance re-check by Stack Trading).

Alt-4 — Second hiatus request submitted while trader is already on leave (Path B):

• No day limit for International Contractor. Always approve — extend stagnation_deadline further by additional Requested_Days. Re-suspending Dots retainer (is_retainer_paused = TRUE) is idempotent — flag already set, no change.
• The Return Protocol (Zapier delay_until) monitors the updated DTO_Hiatus_End_Date. Only one Return Protocol execution occurs on the final extended end date.

(Source: Zapier Integration V7.pdf pp. 21, 228-230, 392-394; client confirmed 2026-09-09)

Alt-2 — Trader's return date passes while Safety Check flags are set:

• Flow triggers Return Protocol automatically on the scheduled end date.
• Safety Check catches the flag → HALT. The account remains Locked indefinitely until Ops manually resolves and triggers re-enablement.
• Manual re-enablement path: Ops calls POST /system/set-account-state with state = "Active" after resolving the compliance/chargeback issue — must be executed via BPS Admin Console (enforces Level_2+/Admin RBAC gate, mandatory reason + transcript_url, logs to BPS_Audit_Log). The endpoint itself is ungated; the Console is the RBAC enforcement point (see BR_9.2.12). (Source: RFQ_ Stack Trading Prop Tech V7.pdf §BPS Endpoints lines 2721–2867; client confirmed 2026-08-27)

Alt-5 — W-2 trader cancels or shortens an approved PTO in Rippling (Path A):

• No automated recalculation. Send a Slack alert to #ops-general (or create a Freshdesk ticket) so Ops can manually verify, re-enable the trading account and adjust stagnation_deadline if needed.
• No corrective ledger entry (Flow 35).
• If the PTO is cancelled before leave_start_date, the waiting Zap (Step A-1.5) will still lock the account on that date — Ops must cancel the pending Zap run or unlock the account manually.

(Source: QnA_BACKGROUND_MECHANISMS_CRON.md [BG-002], [BG-017] — client sheet 2026-11-04)

8. Exception Flows

Exc-1 — Rippling webhook does not pass the entry gate / guard (Path A, Step A-1):

• Worker cannot be mapped to a user_id, Current_Level < 6, or Employment_Type != 'W-2'.
• Do not extend stagnation_deadline; do not lock. Log to BPS_Audit_Log for Ops review. No trader notification.

Exc-2 — Rippling webhook arrives after the leave start date (Path A):

• Case 1 — Today between leave_start_date and leave_end_date: lock immediately for the remainder of the leave; extend stagnation_deadline by the full approved Requested_Days; send a routine Slack notification to #ops-general noting the late approval.
• Case 2 — Today already past leave_end_date: do NOT lock; Flow 35 still logs the PTO on the ledger; extend stagnation_deadline by the approved days; send a routine Slack notification to #ops-general. No Return Protocol scheduled.

(Source: QnA_BACKGROUND_MECHANISMS_CRON.md [BG-003] — client sheet 2026-11-04)

Exc-3 — POST /system/set-account-state call fails OR execution gateway API returns error/timeout:

• Trading account NOT locked as expected. High risk: trader can continue trading during leave.
• Gateway failure handling: Middleware retries up to 3 times with exponential backoff. If all retries exhausted → log to BPS_Audit_Log + send SEV-1 Slack alert to Ops (#ops-it) for manual lock. (Source: Zapier Integration V7.pdf §Flow 13)

Exc-4 — Safety Check alert delivery fails (Head of Ops notification):

• The HALT decision itself is still valid — do not re-enable the account regardless.
• Log the alert failure. Route to secondary alert channel (e.g., Freshdesk ticket, email fallback).

Exc-5 — Trader has an active Flow 14 (Payment Dispute / Chargeback) while on leave:

• If a dispute is raised while trader_status = 'On_Leave', the dispute state takes higher priority than On_Leave: SIM traders → Users.status = 'Banned_Chargeback'; Live traders → dispute hold sets Users.payout_status ≠ 'Approved'.
• The account MUST NOT be automatically re-enabled on the scheduled Return_Date until Admin manually resolves the dispute.
• Safety Check (Step R-1) catches both (conditions 2 and 3) and halts return — this exception documents the scenario where the dispute arises mid-leave so test data setup is clear.

(Source: QnA_BACKGROUND_MECHANISMS_CRON.md [BG-005] [BG-006] — client sheet 2026-11-04)

9. Business Rules

10. Acceptance Criteria

10.1 Open Questions (CR-20261027-001)

11. Update History