DecCF./ˈdɛk.ɛf/

Static bindings and explicit dynamic callbacks

Calculations and cashflows use static callbacks by default. Declare their reads in bindings; the callback receives the resolved values as its first argument and {time, currency} as its second. The model can then prepare the read order before calculating periods. Amounts, rates and decisions can still change each period.

Static callbacks are synchronous, pure calculations of their supplied values. They must not change model declarations or depend on side effects from earlier callback calls. A static flow using the debit/credit shorthand calculates its amount once per occurrence and uses that amount for both postings. Explicit booking amount callbacks remain separate calculations.

The same signature applies to a static flow's active, amount and booking amount callbacks. bindings is an object whose property names become callback value names. Sources may be declared inputs or input projections, calculations or their projections, accounts, flows, expressions, agreement terms, bind references, or scalar literals. Finite numbers, booleans, strings, null and Money literals keep their values. Binding a distribution input reads its central value; explicit temporal sampling uses bind.sample, while a single draw per execution can use bind.once. Repeated components rebind declared references and row projections to the corresponding item.

Static calculation reads of accounts use opening balances in the default period phase and settled balances at phase:'periodEnd'. A static flow reads after preceding account writers. Calculation and flow bindings infer same-period dependencies. Missing references, dependency cycles and a period callback reading a period-end result are errors. Constants and expression amounts remain supported.

Previous values

deccf.bind.previous(reference?) reads the preceding period's calculation value or the account's opening balance. Omit the reference to read the current calculation's previous value. The first calculation value is 0; an account starts with its declared initial balance. Historical reads do not create a same-period dependency. An inactive preceding period uses the calculation's inactiveValue, if supplied; otherwise reading it fails.

Use deccf.bind.previous().project(path) to select a field of the previous self result. A path is a field name, a dotted path or an array of field names, validated against resultType when the model is prepared. The first-period 0 sentinel stays 0, including for text and optional projections. Explicit references can use deccf.bind.previous(other.project('amount')) or deccf.bind.previous(other).project('amount'); chained project calls append path segments. Account previous bindings cannot project fields.

Completed history

deccf.bind.history(calculation?) returns an immutable chronological array of completed calculation values strictly before the current period. The first array is empty. Inactive scheduled periods are omitted. Omitting the reference selects the current calculation. Accounts, flows and future/current values are not history sources. Aggregate a final report from these snapshots and append its current row explicitly; a period state should not carry copies of all previous rows.

Runtime parameters and prepared calculations

deccf.bind.parameter(name, {valueType, defaultValue?}) declares a runtime parameter separate from ordinary model inputs. valueType uses the calculation result schemas, including numbers, Money, text, booleans, records, maps, unions and optional values. The default is used when a run omits that name. A missing required parameter, unknown supplied name, invalid value or conflicting declaration of the same name is an error. Parameter values retain their declared units: use 0.02 for a 2% rate and Money for a currency-bearing amount. Parameters cannot choose accounts, expand entities or change timeline and schedules.

deccf.prepare(model, options?) prepares the fixed structure once and returns an immutable object with .run(options?) and .withParameters(parameters). Preparation accepts ordinary run settings and structural input overrides. Each .run accepts only parameters, seed and trial; changing structural inputs or other settings requires another prepare call. Each run starts with fresh balances, history and once values.

Without outputs, prepared runs return the usual complete result. With outputs:{name:reference}, the result is a frozen record containing only the selected final calculation, calculation projection or account values. Accounts return numbers; calculations retain their native result types, including Money. These are nominal simulation values, without report valuation or series wrappers. Undeclared or unsupported references are rejected. The timeline and balanced postings still run. Unused report, journal and category records may be omitted only when no consumer needs them; dynamic consumers retain their required bookkeeping.

deccf.run(model,{parameters:{contribution:2400}}) also accepts runtime parameters. These values are distinct from deterministic.parameters, whose inputs. names override ordinary model inputs.

Reuse a validated parameter set

prepared.withParameters(parameters) returns a new immutable prepared handle with a validated snapshot of the supplied names. Later changes to the source objects cannot change the snapshot. Chained calls inherit earlier names and replace names supplied again. A replacement replaces that name's entire value; nested records are not merged. Unknown names and invalid values fail immediately. Missing required names may remain unset while preparing or scoping; .run rejects any still missing after its overrides are applied.

Each scoped .run({parameters}) validates only the newly supplied values and leaves its handle unchanged. This is useful when many candidate calculations share a large annual rate path but vary a few amounts. Currency remains the one chosen for preparation; Money parameters must pass its currency validation. Seed and trial can change per run. Shared parameter data never shares account balances, calculation history or resolved once values between handles, runs or trials.

Configuration once per execution

deccf.bind.once(callback) evaluates its synchronous callback at most once per execution or Monte Carlo trial, when first needed. Readers of the same binding share that result during the execution. Its restricted context provides get for declared inputs and parameter/once bindings, and draw/sample for declared distributions. It has no time, account, flow or calculation reads, and rejects time-varying curve inputs. Sampling uses the initialization period without an owner; use bind.sample for static temporal sampling or a dynamic callback for owner-specific sampling. Parameter bindings captured by the callback must also appear in the model's declared bindings. Put row projections directly in bindings so repeated components can rebind them.

A once result contains data: scalar values, model references, and immutable snapshots of plain records and arrays. Functions are rejected at every nesting level, as are Promises and class instances. Precompute annual sampled values into data when a static model needs a reusable stochastic path. Use an explicit dynamic declaration for callbacks that need the current time, owner or balances. Runtime parameter data cannot supply executable callbacks either.

Declared account opening amounts

An account's initial can be a parameter binding or a once binding returning a finite number or Money in the model currency. These initializers are registered when the model is prepared and resolved before periods begin. Historical bindings (previous and history) cannot initialize accounts. An existing initializer callback still uses the full calculation context and follows its account-dependency checks.

Opt into a dynamic context

Set dynamic:true on a calculation or cashflow to receive the broad calculation context as the first callback argument. Use this for state queries, trigger sources, booking amount, owner-specific sampling and other reads outside static bindings. Dynamic callbacks still obey reference, phase, ordering, finite-value and balanced-posting checks. Declare their calculation and account dependencies with dependsOn, readsAccountsFrom and the applicable historical read lists. Dynamic mode does not permit mutation of the compiled graph. Combining dynamic:true and bindings, even an empty binding object, is rejected.

Flow groups propagate their declared execution mode and bindings. Metrics, fields, events and lifecycle callbacks keep their existing context API. When migrating an earlier model, either move its calculation/flow reads into bindings or add dynamic:true to the declaration that uses the old context.

Sample a distribution through time

deccf.bind.sample(distribution, {calendar}) declares a numeric sample for a static calculation or flow binding. calendar is "period" by default: every model period has its own coordinate. "annual" reuses the first represented period's coordinate throughout the same calendar year, including partial first and last years. Readers of the same distribution share that model-wide sample, independently of their owners or evaluation order. Distribution inputs must be declared in the model; other inputs, unknown options and unsupported calendar values are rejected. This is a binding declaration rather than an input or a callback.

Ordinary unseeded calculations use the distribution's center. Explicit input replacements take precedence over sampling. Seeded pseudorandom and Sobol trials use the same global trial identities in ordinary, indexed and worker execution. Units remain those of the distribution: decimal rates use 0.03 for 3%. Annual sampling holds the annual assumption steady; financial callbacks decide how that annual rate affects each monthly amount.

Annual financial returns with hidden shocks and compounding

Keep the editable mean in the input domain and the illustrative standard deviation in model code. A hidden normal shock contributes zero in an ordinary calculation; Monte Carlo samples it through the declared binding. ctx.get(distribution) and ordinary distribution bindings read the center, so those reads alone create no sampled spread. Standard-deviation controls are unnecessary for this app.

Use bind.sample(shock,{calendar:"annual"}) for annually resetting interest, investment returns, inflation or appreciation. Use bind.once(ctx => ctx.draw(shock)) for a fixed contractual assumption or horizon-wide WACC. Reuse the same rate across related objects and comparisons. Tax, fee, VAT, allocation and degradation proportions need their own assumptions; being called a rate does not make them random interest.

Enter this complete example in the calculation model editor. It opens a fresh Run input with Monte Carlo, 64 trials and Sobol selected. The code still returns an ordinary model; the Calculator runs the chosen simulation. November and December share a return, then January starts a new annual sample. Each completed month compounds the previous balance, preserving the return already earned.

For a separate presentation, enter:

For a loan or savings plan, pass the shared sampled rate calculation through the financial object's documented rate source and dependencies. Its native account and flow calculations handle payments and changing balances. Keep its calendar aligned with the model, preserve nominal/effective conversion and require valid rates: above -1 for compounding, nonnegative for ordinary debt, and discount strictly above terminal growth for DCF. A latest sampled return raised to the whole elapsed horizon would rewrite prior returns and is incorrect.