Loans domain pack

loanPlan() composes a recurring loan balance, interest, payment and optional start/end drawdowns from ordinary DECCF fields, scalar calculations and cashflows. It supports a fixed total payment, a contextual payment formula, fixed-principal repayment, interest-only, bullet and a recast annuity. Rates can be constant inputs or a sampled DECCF rate curve.

const { loanPlan } = modules.loans;
const { amount } = modules["financial-formulas"].formulas;
const loan = loanPlan({
  owner: subject,
  openingBalance: principal,
  annualRate,
  payment: amount.shareOf({ amount: income, share: paymentShare }),
});

return defineModel({
  name: "loan projection",
  currency: currencies.USD,
  timeline: periods.monthly({ from: "2026-01", count: 120 }),
  preconditions: { principal, annualRate, income, paymentShare },
  entities: { subject },
  components: { loan: loan.component },
  metrics: { balance: (ctx) => ctx.get(loan.balance) },
});

Amounts use the model currency. Money inputs are checked together when the model runs. An annual nominal rate is divided by periods per year; an effective annual rate is converted to an equivalent period rate. A variable rate is sampled on the model period date. New start drawdowns accrue a full period of interest; end drawdowns occur after payment and start accruing next period.

The model horizon is not a maturity date. A fixed-payment loan may have a remaining balance at horizon. Bullet and annuity rules validate their final payment period and reject new end-period debt at maturity. Unpaid interest is capitalized by default or raises an error with unpaidInterest: "error". No automatic rounding, day-count rule, fee schedule, foreign exchange or delinquency treatment is provided.

Only loan.component is registered in the model. The returned fields, calculations, and flows are ordinary handles for reporting and explicit dependsOn composition. Loan callbacks may read declared inputs, external calculations, and opening accounts; they cannot read current fields or flows.