Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.
/** Internal precision: prices, rates, quantities, ledger amounts. */
export const SCALE = 5;
/** One comparison tolerance. 5dp values are multiples of 1e-5; float noise is ~1e-12. */
export const EPSILON = 1e-6;
export const RoundingMode = {
/** Ties away from zero — matches Postgres round(). (Math.round(-2.5) = -2; Postgres = -3.) */
HalfUp: "halfUp",
/** Away from zero to the next step — scrap allowances. */
Up: "up",
Down: "down"
} as const;
export type RoundingMode = (typeof RoundingMode)[keyof typeof RoundingMode];
/** Exponent-shift: decimal-string round-trip, immune to 1.005-style float artifacts. */
const shift = (value: number, exp: number): number => {
const [m, e = "0"] = value.toExponential().split("e");
return Number(`${m}e${Number(e) + exp}`);
};
export function round(
value: number,
scale: number = SCALE,
mode: RoundingMode = RoundingMode.HalfUp
): number {
if (!Number.isFinite(value)) return value;
const fn =
mode === RoundingMode.Up
? (n: number) => Math.sign(n) * Math.ceil(Math.abs(n))
: mode === RoundingMode.Down
? (n: number) => Math.sign(n) * Math.floor(Math.abs(n))
: (n: number) => Math.sign(n) * Math.round(Math.abs(n));
return shift(fn(shift(value, scale)), -scale);
}
/** Value equality at the one float-noise tolerance. Two 5dp quantities that
* differ only by ~1e-12 float residue (0.98 + 0.02 vs 1) are the SAME
* quantity — use this instead of `===`/`!==` when a raw compare would mistake
* that residue for a real difference (e.g. deciding whether a draw is a full
* draw). `tolerance` defaults to EPSILON; pass a business tolerance only where
* the caller decides what a difference MEANS. */
export function equals(
a: number,
b: number,
tolerance: number = EPSILON
): boolean {
return Math.abs(a - b) <= tolerance;
}
/** Round every part to `scale` so the results sum EXACTLY to `target`, moving at
* most ONE minor unit per part (largest-remainder / Hamilton apportionment).
*
* Independently rounding N parts leaves a residual of up to N/2 minor units.
* Concentrating that residual on a single part is what breaks a part's own
* relative/absolute pair — a tax line stops matching its own `taxPercent`, and
* a provider that re-derives `amount = net × percent` rejects the document.
* Spreading it one unit at a time keeps every part within a minor unit of its
* exact value, which is the bound those provider checks assume.
*
* Parts rounded furthest DOWN receive the surplus first; parts rounded furthest
* UP give a unit back first. Ties resolve by index so the result is stable.
* Refuses when the residual exceeds one unit per part — that is a real
* disagreement between the parts and the target, not a rounding artifact. */
export function distributeRoundingResidual(
exactValues: number[],
target: number,
scale: number = SCALE
): number[] {
const rounded = exactValues.map((value) => round(value, scale));
if (!Number.isFinite(target) || rounded.some((v) => !Number.isFinite(v))) {
throw new Error("Rounding residual inputs must be finite");
}
const sum = rounded.reduce((total, value) => total + value, 0);
// Compare in whole minor units: the residual is an exact integer count of
// them, so this never inherits the float noise of the sum itself.
const residualUnits = Math.round(shift(target - sum, scale));
if (residualUnits === 0) return rounded;
if (Math.abs(residualUnits) > exactValues.length) {
throw new Error(
`Rounding residual of ${residualUnits} unit(s) exceeds ${exactValues.length} part(s)`
);
}
const unit = shift(1, -scale);
const direction = Math.sign(residualUnits);
const order = exactValues
.map((value, index) => ({ index, error: value - rounded[index]! }))
// Surplus goes to the most under-rounded part; a deficit is taken from the
// most over-rounded one.
.sort((a, b) => direction * (b.error - a.error) || a.index - b.index);
let placed = 0;
for (const { index } of order) {
if (placed === Math.abs(residualUnits)) break;
const next = round(rounded[index]! + direction * unit, scale);
// A part may not cross zero. One minor unit is a rounding correction on a
// part that is nearly its rounded value; on a part that rounds to ~0 it
// would instead REVERSE the part's economic direction — a +0.001 tax
// becoming -0.01 against positive revenue, which is the negative-tax-on-
// positive-revenue shape this whole helper exists to prevent. Skip such a
// part and give the unit to the next-most-deserving one.
if (
exactValues[index]! !== 0 &&
next !== 0 &&
Math.sign(next) !== Math.sign(exactValues[index]!)
) {
continue;
}
rounded[index] = next;
placed += 1;
}
if (placed !== Math.abs(residualUnits)) {
// Every remaining candidate would have to flip sign, so the target
// genuinely disagrees with the parts rather than merely rounding away
// from them.
throw new Error(
`Rounding residual of ${residualUnits} unit(s) cannot be placed without reversing a part's sign`
);
}
return rounded;
}
/** The extra whole units to make/procure to cover scrap at `rate`. Ceils to
* whole units — you cannot make a third of a part to throw away — while the
* fractional target itself is NEVER rounded (callers add the two).
* scrapAllowance(4.5, 0) === 0 -> total stays 4.5
* scrapAllowance(31, 0.01) === 1 -> total 32 */
export function scrapAllowance(target: number, rate: number): number {
return round(target * rate, 0, RoundingMode.Up);
}
/** Tax/discount → settlement amount. `decimals` comes from currency.decimalPlaces — data, never a literal. */
export function applyRate(
base: number,
rate: number,
decimals: number
): number {
return round(base * rate, decimals);
}
/** The other half of the value pair: recover the rate an absolute amount implies.
* Rounded to internal scale so the stored rate is a real 5dp fact, not a raw
* float. Precision only flows cleanly one way — a rate derived back from a
* cents-rounded amount is limited by that amount's scale. */
export function deriveRate(amount: number, subtotal: number): number {
return subtotal > 0 ? round(amount / subtotal) : 0;
}
/** The ledger invariant, as a predicate. `tolerance` is a BUSINESS refusal
* threshold, distinct from EPSILON (the float-noise guard): multi-currency
* journals legitimately carry small cross-rate residuals, so callers pass their
* domain tolerance explicitly. The default EPSILON is for contexts that must
* balance exactly.
*
* Use this where the caller decides what an imbalance MEANS — a validator
* returning `{ data, error }`, or a filter listing unbalanced journals. Use
* assertBalanced where the only correct response is to refuse. */
export function isBalanced(
debits: number,
credits: number,
tolerance: number = EPSILON
): boolean {
return Math.abs(debits - credits) <= tolerance;
}
/** isBalanced, for posting paths where an imbalance can only mean "stop": throws
* with the drift so posting refuses rather than mis-posts. */
export function assertBalanced(
debits: number,
credits: number,
tolerance: number = EPSILON,
label = "Journal"
): void {
if (!isBalanced(debits, credits, tolerance)) {
throw new Error(
`${label} does not balance (off by ${round(debits - credits)}); refusing to post`
);
}
}