Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.
Preserved from source baseline
d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.
Current behavior note: This preserved technical body predates the separate Inject simulated data operation. Its “zero-side-effect” and side-effect-isolation statements apply to modeled Interactive Token Sandbox and Monte Carlo runs, not to physical data injection. Injection writes synthetic lifecycle/state-flow instances, tasks, sample documents, attachments and KPI projections into the selected workspace. It requires separate permissions, and purging a batch does not remove the append-only audit trail. Follow the practical guide for the current write boundary, safe-workspace rules and purge limits.
Current behavior update — 11 November 2026. Sandbox human-task decisions can now be synthesized from downstream gateway conditions. With automatic task completion enabled, both Step and Play ask the server for a deterministic, forward-verified outcome; with it off, consultants can inspect inferred outcomes and heuristic probability badges. Input-bound read-only form fields are not submitted as answers. These weights create synthetic route variety and are not observed approval rates or business policy. Physical data injection is more narrowly scoped: it accepts only a resolvable published lifecycle revision; drafts and standalone process flows are rejected. See the current gateway and published-lifecycle contracts in the Simulation Studio feature specification and the practical guide. The historical body below remains preserved from its stated baseline. Gateway option weights depend on available paths; common zero-config mixes include 80/20 for primary/alternate, 70/20/10 for primary/alternate/default, and 65/20/10/5 when all four categories are feasible. They are not observed approval rates.
Simulation Studio (SCRUM-3398)
Simulation Studio provides a sandboxed, zero-side-effect consultant environment for testing, explaining, branching, and regression-verifying any Lifecycle or Process Flow model before or after publication. Current source owners are SimulationService, MonteCarloSimulationRunner, ProcessSimulationTwinController, and LifecycleJourneySimulator.tsx.
1. Capability-Gated Entry & Revision Pinning (FR-01, FR-08)
- Authorized Entry: The
Simulateaction in the Lifecycle Designer (data-agent-id="lifecycle-simulate-btn") and Process Flow Designer (data-agent-id="pd.flow.tb.simulate") is rendered only when the current user holds scopedprocess:readorprocess:updatecapability for the active workspace and object. Unauthorized users see neither the control nor any simulation catalog/session requests. - Exact Revision Pinning: Every simulation session pins its exact source (
DRAFTsnapshot orPUBLISHEDrevision), computes a deterministic SHA-256pinnedRevisionHash, and records all referenced subprocess and form definitions (referencedDefinitions). Subsequent draft edits or new publications never mutate an in-flight simulation session or saved report. - Side-Effect Isolation: Simulation runs never write to production case tables, never enqueue live human tasks, and never invoke external HTTP connectors, plugins, messaging brokers, or notification channels. Every service/script/external step records a
SimulationExternalOperationReceiptindicating whether it was satisfied by an explicit fixture (SIMULATED_WITH_FIXTURE), evaluated internally (INTERNAL_EVALUATED), or flagged as missing a fixture (UNRESOLVED_MISSING_FIXTURE).
2. Scoped Variable Inspector & Presence Semantics (FR-02, FR-10)
The Scoped Variable Declarations inspector (SimulationVariableDiffTree.tsx) surfaces all declared variables across LIFECYCLE, PROCESS, and SUBPROCESS scopes from step 0 onward without seeding synthetic defaults for unset variables:
| Presence Badge | Meaning |
|---|---|
UNSET |
Declared on the lifecycle/process/subprocess model, but no initial input, default, or task/service output has written to it yet. |
DEFAULTED |
Populated from the declaration's configured defaultValue at session start (origin: DECLARED). |
NULL |
Explicitly written with a null value (distinct from UNSET). |
FALSE |
Explicitly written boolean false (never conflated with UNSET or NULL). |
ZERO |
Explicitly written numeric 0 (never conflated with UNSET or NULL). |
EMPTY_STRING |
Explicitly written "" (length 0, distinct from UNSET and NULL). |
WRITTEN |
Written by start input, human task output mapping, script/service fixture, or subprocess output propagation. |
- Provenance & Shadowing: Each variable row displays its
type,scope(LIFECYCLE,PROCESS, orSUBPROCESS:<nodeId>),origin(DECLARED,START_INPUT,TASK_OUTPUT,SCRIPT_OR_SERVICE,RUNTIME_SYNTHETIC), and a clickable link to thelastWriterNodeIdandlastWriterBinding. When a subprocess declares a variable with the same name as a parent scope variable, both rows remain distinct and displayShadows/Shadowed byindicators.
3. Interactive Human-Task Action & Output Mapping (FR-03)
When a simulation token reaches a userTask, execution pauses and exposes a SimulationPendingHumanTask card (data-agent-id="sim-pending-task-card-<nodeId>"):
- Configured Actions & Custom Forms: Consultants can click any configured task outcome button (
data-agent-id="sim-task-action-<nodeId>-<actionId>"), edit typed form fields (data-agent-id="sim-task-field-<nodeId>-<fieldName>"), or test the missing-decision path via Step Without Decision (UNSET) (data-agent-id="sim-task-omit-<nodeId>"). - Generated Single Approval Parity: Matches runtime form normalization—selecting
ApproveorRejectwrites title-case"Approved"or"Rejected"to the task'sdecisionfield before applying the configured output mapping (activity.output.form.decision.target/activity.output.decision.target) to the target process variable. Custom forms preserve their exact configured values. - Full Binding Operations: Supports
SET,ADD/APPEND,REMOVE, andAT_INDEX(indexExpression), plusUPPER,LOWER,TRIM,NUMBER, andBOOLEANtransforms.
4. Gateway & Transition Routing Explainability (FR-04, FR-10)
Whenever a token evaluates an Exclusive (XOR), Inclusive (OR), or Lifecycle state transition gateway, Simulation Studio records a SimulationGatewayObservation using the same expression semantics as runtime (ProcessEvaluationContext.withDeclaredNulls and InflowExpressionEvaluator):
- Per-Branch Evaluation Table: Lists every outgoing sequence flow in evaluation order with its condition expression, actual operand values, operand presence state (
WRITTEN,UNSET,NULL, etc.), producer node/binding link, and evaluation status (TRUE,FALSE,SKIPPED,MISSING,INVALID,DEFAULT_SELECTED, orUNCONDITIONAL). - Missing Decision & No-Path Diagnosis: If a gateway condition references a declared variable that is still
UNSETand no default branch matches, the branch is markedMISSINGand the gateway reportsNO_PATH_ERROR(ENGINE_GATEWAY_NO_PATH) with a clear explanation of which variable was unset and which upstream task or binding was expected to write it.
5. Non-Destructive Rewind, Run Branching & Idempotent Stepping (FR-05)
- Non-Destructive Rewind: Rewinding or scrubbing the timeline (
POST /api/process-simulation/sessions/{id}/rewind) repositionscurrentStepIndexwhile preserving all later snapshots for read-only inspection. - Run Branching (Forking): Clicking Branch Run (
data-agent-id="sim-btn-branch-from-step"/POST /api/process-simulation/sessions/{id}/fork) creates a child session anchored atparentSessionIdandforkedFromStepIndexso consultants can explore an alternate human action or fixture without overwriting the baseline run. - Idempotent Step Commands: Every step command carries a
commandId(commandKey) andexpectedStepIndex. Duplicate retries return the cached snapshot without double-stepping; stale step indices fail with409 SIMULATION_STEP_CONFLICT.
6. Saved Scenarios, Assertions & Revision Comparison Reports (FR-06, FR-07)
- Reusable Scenarios & Regression Suite: Consultants can save named scenarios (
POST /api/process-simulation/scenarios) containing initial variables, fixtures, human-task step actions, virtual-time advances, and assertions (VARIABLE_EQUALS,VARIABLE_PRESENCE,TRANSITION_TRAVERSED,GATEWAY_OUTCOME,TERMINAL_STATUS,ERROR_CODE). Running all scenarios (POST /api/process-simulation/scenarios/run-all) flags anystaleRevisionmismatch and catches output-mapping or condition regressions acrossApprove,Reject, andMissing decisionpaths. - Revision Comparison & Redacted Reports: Consultants can compare two simulation sessions (
POST /api/process-simulation/compare) to inspect variable, transition, and gateway diffs, and generate shareable run reports (POST /api/process-simulation/reports). Sensitive variables and fixture keys matching credential patterns (password,secret,token,apiKey,authorization,privateKey,clientSecret,credential) are automatically masked (***REDACTED***), and reports can be revoked (POST /api/process-simulation/reports/{id}/revoke) or expire viaretentionMinutes.
7. Virtual Time, Seeded Batch Analysis & Performance (FR-09, T010)
- Deterministic Seed & Virtual Clock: Both interactive sessions and Monte Carlo batch runs accept an explicit
seedso identical seeds and inputs produce identical traces, timer firings (timerEventsFired), and branch distributions. - Bounded Cancellation & Explicit SLA Assumptions: In-flight batch runs can be cancelled immediately via
POST /api/process-simulation/batch/{batchRunId}/cancel(data-agent-id="sim-btn-cancel-batch"). Batch reports surface explicitslaAssumptionsalongside failure/blocked run counts. - Measured Scale & Latency (
T010): Verified inSimulationServiceTest.shouldMeetInteractiveStepLatencyTargetAndCancelBatchCleanlyon a 100-node workflow with 200 declared variables (p95step latency< 50 ms, well below the< 1000 msinteractive target).