Page 20 of 23

Orchestration Internals

This page documents how plan calculations execute on the Salesforce Platform—for implementers and support engineers. End users should start with Running Calculations.

Enqueue path

LWC (Plan Preferences or auto-update path) calls FinPlan_Plan_Orchestration Apex.
Server validates plan state and blocks duplicate enqueue while isServerInFlight (Submitted, Processing, DTO_Ready).
FinPlan_Orchestration_Queueable (and related queueables) execute calculation stages.
Outputs persist to projection and tax objects; status fields update on the Financial Plan.
UI polls via finPlanOrchestrationStatusCoordinator (single interval per plan).

Status contract

Authoritative lifecycle rules live in FinPlan_OrchestrationStatusContract (Apex). The LWC mirror finPlanOrchestrationStatusContract must stay in lockstep when semantics change.

Helper	Purpose
`isServerInFlight`	Block duplicate server enqueue
`shouldPoll`	Continue UI polling through Completed
`isTerminal`	Stop polling on Ready, Failed, Out of Date
`isDtoAvailable`	Phase-1 projection marker present
`isUiBlocking`	Spinner/navigation hold rules

DTO_Ready semantics

DTO_Ready signals Phase-1 projection availability for UX (charts, toasts) before the persistence tail completes. Markers:

Last_Run_Dto_Ready_At__c — epoch timestamp for UI correlation
Last_Run_Id__c — run-id correlation with finPlanOrchestrationDtoAck

Chart refresh uses Lightning Message Service (OrchestrationCompletionInternalChannel) and orchestrationLmsShouldRefreshProjectionCharts—refresh on DTO_Ready and Failed, not redundant second passes on Ready when DTO already fired.

Split-phase persistence and Platform Cache

FinPlan_SyncStagingCache stages artifacts in the org cache partition (optional fast path). When cache is unavailable (StagingCacheUnavailableException), queueables fall back to inline or monolithic persistence paths. Correctness must never depend on cache presence.

Partition: FinPlanSyncPersistence (approximately 2 MB, TTL 600s in packaged defaults).

Monte Carlo separation

Monte Carlo uses chunked queueables and platform events with its own status vocabulary. Do not conflate Monte Carlo progress strings with Orchestration_Status__c picklist values.