construction.retention

pub fn retention(cumulative_value: &Money, basis_points: i64, stage: &str) -> Retention

// RetentionStage is a string in Rust, one of: "interim", "practical-completion", "final".
// Parameters take it as &str and results hold it as String.

/// The retention on one valuation, and how much of it has been let go.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Retention {
    /// the full percentage on the cumulative value
    pub full: Money,
    /// what this valuation keeps back
    pub held: Money,
    /// full less held: what has been released so far
    pub released: Money,
}

fune!(construction.retention@^1);  // then call retention(…)

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one
use super::math_round_div::round_div;  ← from math.round-div ^1.0.0 · built alongside by fune
use super::money_amount::{money, money_from_value, money_to_value, Money};  ← from money.amount ^1.0.0 · built alongside by fune

const MAX_SAFE: i128 = 9_007_199_254_740_991;

/// 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.
///
/// # Panics
/// Panics on a percentage outside 0..=10000, a negative value, an unknown
/// stage, or a product beyond 2^53 - 1.
pub fn retention(cumulative_value: &Money, basis_points: i64, stage: &str) -> Retention {
    if !(0..=10000).contains(&basis_points) {
        panic!("basisPoints must be a whole number from 0 to 10000, received {}", basis_points);
    }
    if cumulative_value.minor < 0 {
        panic!("cumulativeValue must not be negative, received {}", cumulative_value.minor);
    }
    let product = cumulative_value.minor as i128 * basis_points as i128;
    // i64 could go further, but TypeScript cannot, and all three must agree.
    if product > MAX_SAFE {
        panic!("the retention calculation exceeds 2^53 - 1");
    }
    let product = product as i64;
    let full = round_div(product, 10000, "half-up");
    let held = match stage {
        "interim" => full,
        "practical-completion" => round_div(product, 20000, "half-up"),
        "final" => 0,
        other => panic!("unknown retention stage \"{}\"", other),
    };
    let currency = &cumulative_value.currency;
    Retention {
        full: money(full, currency),
        held: money(held, currency),
        released: money(full - held, currency),
    }
}

pub fn retention_to_value(r: &Retention) -> Value {
    Value::obj(vec![
        ("full", money_to_value(&r.full)),
        ("held", money_to_value(&r.held)),
        ("released", money_to_value(&r.released)),
    ])
}

pub fn fune_vector(args: &[Value]) -> Value {
    if let Value::Float(f) = &args[1] {
        panic!("basisPoints must be a whole number from 0 to 10000, received {}", f);
    }
    retention_to_value(&retention(
        &money_from_value(&args[0]),
        args[1].as_i64(),
        args[2].as_str(),
    ))
}

Install

fune build

With that line in your source, in a Rust project (language rust in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the Rust 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. A crate’s build.rs runs it before every compile. Or pin a range in fune.project and build in one step:

fune add construction.retention

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

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