Calculators

Status: shipped 2026-09-04 (072). Authority: this document is the user-facing catalog; the registry is CalculatorRegistry, and CalculatorRegistrySpecDriftTest fails the build if the two ever disagree in either direction — including on an input's name, its type, whether it is optional, and the worked example's answer.

Design record: Calculators — Configurable Pure Transformations §0.

1. What a calculator is

A calculator is a pure function the server ships: typed inputs in, one typed value out — or, for a multi-output kind, a named SET of typed values out. You use one by putting a CALCULATOR node in a pipeline (Pipeline Contract §4.10):

{ "id": "fiscal_q", "type": "CALCULATOR",
  "kind": "fiscal_quarter",
  "inputs": { "date": "$current_date", "fiscal_start": "$org_fiscal_start_date" },
  "context_key": "run_fiscal_quarter",
  "depends_on": [] }

The node writes one value into the execution Context under context_key, and every node that depends_on it — directly or transitively — can bind it as :run_fiscal_quarter.

A kind whose answer is genuinely several values (a window is two dates, not one) declares a set of named outputs instead, and the node maps every output to a Context key through context_keys:

{ "id": "window", "type": "CALCULATOR",
  "kind": "period_bounds",
  "inputs": { "date": "$current_date", "unit": "quarter" },
  "context_keys": { "start": "window_start", "end": "window_end" },
  "depends_on": [] }

Every declared output must be mapped — no partial windows — and each mapped key obeys the same rules a single context_key does: the name shape, one writer per key, no shadowing a declared parameter, and the ordering rule below. context_key XOR context_keys: never both, never neither, and the field always fits the kind — a kind's output shape is the catalog's, not the author's.

Three rules are worth learning once:

1. $name is a reference, anything else is a literal. "fiscal_start": "$org_fiscal_start_date" reads the deployment's setting; "fiscal_start": "09-15" pins this pipeline's own. The literal is type-checked against the input at save time, and so is a reference whose type is knowable at save (org/platform key, declared parameter, another calculator's typed output).
2. Ordering is depends_on, not array position. A reference to another calculator's context_key, or a SQL node binding one, is valid only if the reader depends on the writer. Otherwise the save is refused with pipeline.validation.calculator_input_unordered — the node would otherwise read a key that may or may not have been written yet, depending on scheduling.
3. A calculator is not for row data. It computes ONE value — or one named set of values — for the whole run. Transforming columns is SQL's job — on the source engine, or in tempdb, reused through a library template (Templates §6).

Each kind also declares the everyday phrases it answers (the Phrases column below) — match a question's words against them to choose the kind; that lookup, not any rule, is how a relative time phrase gets its interpretation.

The keys you can reference without declaring anything

Anything else must be a declared pipeline parameter or another calculator's context_key. The full precedence table is Pipeline Contract §7.2.

2. The catalog

Reading a signature: `name` is an input, ? marks it optional, [] marks a JSON array, and ANY means the kind does not look at the value's type. Types are the canonical ones (Type System §3). The Phrases column lists the everyday phrases the kind answers — the lookup path for a relative phrase in a question: match the question's words against them to choose the kind, rather than being told what any phrase means.

2.1 Calendar and time

Two conventions these kinds fix, so that nothing has to guess. A fiscal year is labelled by the calendar year it starts in — with fiscal_start = "04-06", 2026-01-15 is fiscal year 2025. (Deployments that label by the ending year, as the US federal government does, add 1 in SQL or declare a parameter.) And 02-29 is a legal fiscal_start: it resolves to 02-28 in a non-leap year, which is what MonthDay.atYear does and what ConfigValidator accepts it for.

mode is calendar or fiscal and decides how quarter and year boundaries fall. A month is a month in both — no fiscal calendar in use redefines a month's boundary, and pretending mode mattered there would invite an author to expect that it did.

Two grammars are contract, not implementation detail: format is a Java DateTimeFormatter pattern, and every zone is an IANA id. A fixed offset such as +02:00 is deliberately not a zone id.

tz_shift re-reads a wall-clock time, so it meets daylight saving head on. A reading that lands in the spring-forward gap (02:30 on a night the clocks jump 02:00 → 03:00) is moved forward by the gap's length, and one in the autumn overlap takes the earlier of the two offsets — Java's ZonedDateTime rules, stated here because a kind's grammar is contract.

2.2 Numeric

Both are BigDecimal end to end. A money figure that passed through a double on its way is the defect this choice exists to prevent, which is also why percent_change refuses a zero previous rather than reporting infinity.

2.3 Values

map carries its lookup in the node — parallel from/to arrays, so each element types like any other literal. It is for a handful of pairs an author can read at a glance; a lookup with hundreds of rows belongs in a table and a SQL join.

3. When it fails

A calculator that cannot evaluate the inputs it was given fails its node with pipeline.node.calculator_failed (Pipeline Contract §13.4). The failure record names the kind, the input at fault and the reason — an unknown unit, a format that does not compile, text that does not match its pattern, a zero denominator. The execution then fails fail-fast like any other node failure, and the record reaches SSE, executions_get and the run's detail page unchanged.

Most defects never get that far: kind exists, every required input is present, literals type-check, context_key is well-named and collides with nothing, and every $reference resolves to a key that is genuinely upstream — all of that is refused at save time (Pipeline Contract §12.10).

4. Growing the catalog

The catalog is additive, forever. A kind is written into pipeline bodies that are versioned, exported and promoted, so removing one — or changing what one computes — breaks a body that already validated. A changed meaning is a new kind with a new name.

Adding one means: the kind in modules/calculators, its unit tests, and its row in this document, in the same commit. The drift guard makes that non-optional in both directions.