> ## Documentation Index
> Fetch the complete documentation index at: https://help.stralos.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Calculator input links

> Linking a calculator's length or area input to a takeoff measurement total or tag subtotal

`@stralos-co-nz/calculators` (from 1.9.0, `packages/calculators/src/calculatorInputLinks.ts` in `stralos-domain`) defines the contract for linking a trench, pit, or volume calculator's length or area field to takeoff. The resolved value is written into the calculator's `config` (`config.length`, `config.lengthM`, or `config.areaM2`), so the engine and every config type are unchanged. Calculator input links are stored in `estimate_calculators.input_links`.

A calculator input takes takeoff sources only: a measurement's total, or the sum of one or more of its tag subtotals (from calculators 1.14.0). Tag subtotals come from a Multi-segment or tagged Multi-line and are in metres, so only a length field can take one. A link that holds a measurement's total and one of its own tag subtotals is refused with `takeoff_overlap`, as for any other target. The resolution graph must stay acyclic: takeoff → calculator inputs → build-up lines → work items.

## Linkable fields

| Field | Arm | Mode | Unit |
| - | - | - | - |
| `trench.length` | trench | any | `metre` |
| `pit.lengthM` | pit | any | `metre` |
| `volume.lengthM` | volume | `lwd` only | `metre` |
| `volume.areaM2` | volume | `areaDepth` only | `square_metre` |

`pit.lengthM` is linkable from calculators 1.17.0; other pit fields are not. `calculatorLinkableFieldUnit(field)` returns `"metre"` or `"square_metre"`, the unit passed as `workItemUnit` when resolving the link.

`calculatorLinkableFieldApplies(field, calculator)` returns whether the field exists on the calculator as currently configured. A mode switch that makes a linked field inapplicable orphans its link and the server raises a 409 `calculator_source_removed`.

## `CalculatorInputLinksV1`

```ts theme={null}
type CalculatorInputLinksV1 = {
  v: 1;
  fields: Partial<Record<CalculatorLinkableField, QuantityLinkV1>>;
};
```

Each entry in `fields` is a `QuantityLinkV1` descriptor validated with `quantityLinkTargetIssues(link, "calculatorInput")`: takeoff sources only, including tag subtotals. A non-takeoff source raises `target_source_kind`. The unit check happens at resolution, not here: a tag subtotal on `volume.areaM2` resolves with a `unit` mismatch, which api-estimate refuses on write as `422 quantity_link_unit`. Resolution uses `resolveQuantityLink` with `calculatorLinkableFieldUnit(field)` as `workItemUnit`.

## Validation

`@stralos-co-nz/calculators` has no whole-value validator for `input_links` (`calculatorInputLinksIssues` was removed in calculators 2.0.0). api-estimate checks the top-level shape with its own strict schema, `calculatorInputLinksSchema` in `src/quantityLink/calculatorInputs.ts`: `v` must be `1`, and `fields` may hold only keys from `CALCULATOR_LINKABLE_FIELDS`, each a `QuantityLinkV1`. Each changed link is then checked with `quantityLinkTargetIssues(link, "calculatorInput")`.

Whether a field applies to the calculator's current mode is `calculatorLinkableFieldApplies`, which needs the config and is the host's check.

## Constants

| Export | Value |
| - | - |
| `CALCULATOR_INPUT_LINKS_VERSION` | `1` |
| `CALCULATOR_LINKABLE_FIELDS` | `["trench.length", "pit.lengthM", "volume.lengthM", "volume.areaM2"]` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.