construction.retention

export function retention(cumulativeValue: Money, basisPoints: number, stage: RetentionStage): Retention

export type RetentionStage = "interim" | "practical-completion" | "final";

/** The retention on one valuation, and how much of it has been let go. */
export interface Retention {
  /** the full percentage on the cumulative value */
  readonly full: Money;
  /** what this valuation keeps back */
  readonly held: Money;
  /** full less held: what has been released so far */
  readonly released: Money;
}

import { retention } from "#fune/construction.retention@^1";

import { roundDiv } from "./math_round_div.ts";  ← from math.round-div ^1.0.0 · built alongside by fune
import { type Money, money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { type Retention, type RetentionStage } from "./construction_retention_types.ts";

/**
 * Retention on a valuation, the way JCT-style contracts release it.
 *
 * Retention is always worked out afresh on the cumulative value, never
 * accumulated valuation by valuation, so a later valuation corrects an earlier
 * one. At practical completion half the percentage applies (not half of a
 * figure rounded earlier), and after the defects are made good none does.
 */
export function retention(cumulativeValue: Money, basisPoints: number, stage: RetentionStage): Retention {
  if (!Number.isInteger(basisPoints) || basisPoints < 0 || basisPoints > 10000) {
    throw new RangeError(`basisPoints must be a whole number from 0 to 10000, received ${basisPoints}`);
  }
  if (cumulativeValue.minor < 0) {
    throw new RangeError(`cumulativeValue must not be negative, received ${cumulativeValue.minor}`);
  }
  const product = cumulativeValue.minor * basisPoints;
  if (!Number.isSafeInteger(product)) {
    throw new RangeError("the retention calculation exceeds 2^53 - 1");
  }
  const full = roundDiv(product, 10000, "half-up");
  let held: number;
  if (stage === "interim") held = full;
  else if (stage === "practical-completion") held = roundDiv(product, 20000, "half-up");
  else if (stage === "final") held = 0;
  else throw new RangeError(`unknown retention stage "${stage}"`);
  const currency = cumulativeValue.currency;
  return { full: money(full, currency), held: money(held, currency), released: money(full - held, currency) };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add construction.retention

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./construction.retention-1.0.0-typescript.fune, or fetch it from a terminal with fune pull construction.retention@1.0.0:typescript.

The whole function, every language, is one file too: construction.retention-1.0.0.fune, 17,797 bytes, sha256 3af86f923a327011e14fe345cb3d8f3ecec00bc9d184e6f288c24ed4a47f2132. It installs into a project of any language.

// fune: before construction.retention

// fune: after construction.retention

// fune: replace math.round-div in construction.retention
// fune: replace money.amount in construction.retention

// fune: step construction.retention after <n|label>

More from the author

- **Work it out on the cumulative value, every time.** Valuations are cumulative (everything done to date), and so is retention: pass the gross value certified to date (work done plus materials on site), not this month's increase. A later valuation then corrects an earlier one automatically, and `construction.valuation` takes the previous payments off the net figure. - **The usual release pattern.** Before practical completion the full percentage is held (`interim`). At practical completion half of it is released: the retention becomes **half the percentage on the value** (`practical-completion`), which is how JCT contracts word it. After the end of the rectification (defects) period, when the defects are made good, the rest is released (`final`, nothing held). - `released` is `full - held`, the total released so far, not the release in this valuation.

## Rounding

Each figure is one rounding of an exact product, half up to the minor unit: `full` is value x percentage, `held` at practical completion is value x percentage / 2. Halving the already rounded full retention can differ by a penny: 5% of 10,000.10 is 500.005 (500.01) and 2.5% is 250.0025 (250.00), where half of 500.01 would round to 250.01.

## Edges and limits

Percentages are basis points from 0 to 10000; the common figures are 3% and 5%. Negative values are refused (a valuation below the previous one is still a positive cumulative value). Contracts that cap retention at a fixed sum, or release it in more than two parts, are not modelled: compute the cap in the caller, or call this with the stage that applies. value x percentage must stay within 2^53 - 1.

Source: the JCT Standard Building Contract (2016 edition, section 4, rules on retention: the Retention Percentage, 3% unless stated, halved after practical completion). The contract text is not freely published, so this was not checked against it; the percentage and stages are whatever your contract states.

Files