v5.31.0 28 May 2026 Feature Improvement

Fractional Pricing & Exact-Decimal Invoice Calculation

Why This Matters

Invoicing is where SpeyBooks touches money most directly, so the calculation path has to be exact, not approximately right. This release closes three gaps in that path. Unit prices can now carry up to six decimal places, which makes usage-based and metered billing (per-request, per-unit, per-kWh, FX-derived rates) representable without silent truncation. The values written to fractional-decimal columns now cross the database boundary as exact decimal strings rather than floating-point numbers, removing a class of rounding error before it can occur. And two of the monetary invariants that previously relied on a single enforcement layer now have a second, independent layer that runs automatically in CI and on every deploy.

None of this changes existing invoices: every amount already stored produces an identical result under the wider precision. The integer-pence guarantee at the heart of the ledger is unchanged. What changed is the range of pricing the system can represent exactly, and the number of independent mechanisms that prove it.

Fractional Pricing

  • Unit prices to six decimal places Invoice and quote line unit prices now support up to six decimal places. This is for pricing models where the unit rate is a fraction of a penny, metered API billing, per-unit cloud or bandwidth charges, commodity and energy rates, and currency-derived per-unit prices. Previously unit prices were capped at two decimal places, which forced these models to be approximated or scaled by hand.

  • Derived amounts still round to whole pence Every net, VAT, and gross amount is still computed and stored as integer pence, rounded at the calculation boundary using the canonical half-up rounding rule. Finer unit-price precision changes what you can express as an input; it does not introduce fractional pence into any stored amount.

Exact-Decimal Calculation

  • Exact decimal wire encoding Values destined for fractional-decimal columns (quantity, unit price, VAT rate) are now serialised as exact decimal strings when written to the database, never as floating-point numbers. A value such as a 17.5% rate or a sub-penny unit price is stored exactly as written, with no binary floating-point intermediate that could introduce a representation error. Whole-pence amounts continue to be written as integers, which is exact for them.

  • VAT rate precision The stored VAT rate now carries enough precision to represent rates finer than whole percentages, aligning the column with the calculation standard and removing a latent truncation point for non-standard rates.

Mechanical Enforcement (Class M)

Two monetary invariants move to full two-layer mechanical enforcement in this release. Under the SpeyBooks truth model, an invariant is only described as enforced when a violation causes immediate, automatic failure at more than one independent layer.

  • Exact decimal wire encoding is now mechanically enforced. A continuous-integration gate scans the financial code paths and fails the build if a value is written to a fractional-decimal column as a floating-point number without an explicit, reviewable integer-column exemption. This sits alongside the application-layer change above, giving the invariant two independent layers.

  • Stored-amount magnitude envelope is now mechanically enforced. A database-level guard rejects any stored monetary amount whose magnitude falls outside the range the overflow analysis covers, well before the underlying integer type could be exceeded. A deploy-time check confirms the guard is present and correctly bounded on every release. The widening of unit-price precision was proven safe against integer overflow before it shipped; this envelope converts that proof into a standing, enforced guarantee.

Proof Anchors

Application layer:
  Exact decimal serialisation on fractional-decimal writes in the
  invoice calculation path (AX-MON-003).

CI layer:
  Static gate fails the build on an unannotated floating-point write
  to a fractional-decimal column — migration 086 / kernel CI (AX-MON-003).

Database layer:
  Magnitude-envelope constraints on stored amounts; unit-price and
  VAT-rate precision widening — migration 085, migration 086 (AX-MON-004).

Deploy / CI verification:
  verify-axiom-coverage  — PASS (29 delivered Class M invariants, 0 violations)
  numeric wire-encoding gate — PASS (0 violations)
  magnitude-envelope check   — PASS (live constraints verified)
  system reconstruction      — PASS

Operational Impact

  • Usage-based and sub-penny pricing models are representable without manual scaling or approximation.
  • Zero floating-point intermediates on fractional-decimal writes in the invoice path.
  • Existing invoices and quotes are unchanged: the precision widening is value-preserving, with no recomputation.
  • Two monetary invariants now fail closed at two independent layers each, enforced on every build and deploy.

Files Changed

Backend: Invoice calculation service, monetary schema migrations, axiom registry, kernel CI and deploy verification gates.

Known Issues

  • Quote line calculation is being brought onto the same calculation standard as invoices in a follow-up release; quote totals are unaffected by this release’s changes.

This release tightens the invoice calculation path to exact-decimal precision and widens what SpeyBooks can price, with both changes standing on mechanical proof rather than convention.