DecCF./ˈdɛk.ɛf/

Calculation progress

Monte Carlo runs show progress automatically in the Calculator. After 300 ms of execution, the input toolbar softly reveals a ring; fast runs show no indicator. Before completed-work feedback arrives, the ring is indeterminate. The percentage then follows actual completed work across the whole request, including scenarios. It does not estimate remaining time: one trial can take longer than another.

The ring softens from 90% while its percentage remains readable. It stays below 100% until success is accepted, shows 100% briefly, then fades. Cancellation, errors or replacing the run clear it without showing 100%. Your previous report stays visible, the layout stays stable and controls remain usable. Reduced-motion preferences remove transitions.

Financial models declare assumptions and calculations. They need no progress UI, timers, polling or custom simulation loops. The Calculator owns this feedback.

Optional calculation observations

deccf.runMonteCarlo(model, options, {onProgress}) accepts an optional third control argument, defaulting to {}. Existing calls with two arguments retain their behavior. The function remains synchronous and returns the same calculation result. Observing it does not make a synchronous call paint a progress display. See the complete public API reference for a callable example.

The observer receives immutable snapshots with these fields:

FieldMeaning
phasepreparing, baseline, trials, finalizing or successful complete
completedTrials, totalTrialsFinished trials and declared trial count
completedWork, totalWorkFinished work and total work, including baseline and final summary
baselineCompleteWhether the ordinary base calculation has finished

For N trials, totalWork is N + 2: one baseline, N trials and one final summary. Baseline order follows the selected execution strategy. Observations may be coalesced; an observer must not expect one call per trial. Callback errors do not affect calculation results and returned promises are not awaited. Keep observers brief. A failed calculation never announces complete.

The callback belongs only in the separate controls argument. It is absent from run options, result data, receipts and cache identities. A Web API request sends only its ordinary JSON calculation body, never a callback.

Optional Web API feedback

Use the published API's ordinary calculation operation or its /presentation operation with the same authorization, request body and run settings. Ordinary OpenAPI/Swagger requests receive application/json and keep their current result schemas. Live feedback is an optional HTTP response format:

Accept: application/x-ndjson
Content-Type: application/json

This observes a single execution with its usual credit cost. It does not start a second simulation. A client must inspect the response's Content-Type and accept ordinary JSON when feedback is unavailable. Authentication, validation and admission failures before streaming retain their ordinary HTTP status and JSON error body.

An application/x-ndjson response contains one JSON frame per line. Each has version: 1 and one of these shapes; responseBody means the unchanged JSON response of the selected endpoint:

({version: 1, type: "progress", progress: {
  phase: "trials", completedTrials: 16, totalTrials: 64,
  completedWork: 17, totalWork: 66, baselineComplete: true,
}});
({version: 1, type: "result", value: responseBody});
({version: 1, type: "error", error: safeErrorBody, status: 422});

Progress snapshots use the fields above. Across S equally sized scenario runs, totalTrials is N * S and totalWork is (N + 2) * S; completed counts do not reset between scenarios. An individual baseline or trial can finish without intermediate feedback.

Exactly one terminal frame is required: either result or error. A result's value retains the complete ordinary response envelope, including its result names and order; /presentation keeps its usual projected data. An error contains the endpoint's existing sanitized public error fields, with its ordinary HTTP error code in status when streaming has already started. The example's 422 is illustrative; use the frame's actual status. A progress frame, even at complete work, is not accepted success. Show 100% only after a valid terminal result has been accepted. Errors and canceled, malformed, oversized or truncated streams must never imply success. Closing the response cancels the same operation.

A terminal result can also carry optional headers metadata. Only the normal response's x-deccf-credits, x-deccf-credit-usage-id, x-deccf-app-id and x-deccf-version-id values are allowed. Treat these as informational metadata; the calculation body remains solely in value.