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.
import {
assertCurrencyDecimals,
assertExchangeRate,
calculateSettlementFx,
toBaseAmount,
toDocumentAmount
} from "@carbon/database/accounting-currency";
import { round } from "@carbon/database/precision";
/**
* The document a customer deposit secures (`payment.rentalAgreementId` /
* `payment.salesOrderId`). A deposit funds only invoices that bill that
* document — a `salesInvoiceLine` carrying the same id — never the customer's
* other invoices. An unscoped source funds anything.
*/
export type FundingScope = {
type: "rentalAgreement" | "salesOrder";
/** The document's row id, as stored on the payment and the invoice line. */
id: string;
/** Readable id (RA000001, SO000123) for messages; optional. */
readableId?: string | null;
};
export type FundingSource = {
paymentId: string;
postingDate: string;
exchangeRate: number;
remainingDocument: number;
/** Original carrying base less effective recorded funding releases. */
remainingBase: number;
/** Set when the source is a customer deposit; absent or null funds anything. */
scope?: FundingScope | null;
};
export type FundingRequest = {
targetId: string;
targetExchangeRate: number;
remainingDocument: number;
/** Original target carrying base less effective recorded base relief. */
remainingBase: number;
requestedDocumentPrincipal: number;
discountAmount: number;
writeOffAmount: number;
/** Rental agreements the target invoice bills (`salesInvoiceLine.rentalAgreementId`). */
rentalAgreementIds?: readonly string[];
/** Sales orders the target invoice bills (`salesInvoiceLine.salesOrderId`). */
salesOrderIds?: readonly string[];
};
/** The deposit scope a payment row carries, or null for an ordinary payment. */
export function fundingScopeOf(row: {
rentalAgreementId?: string | null;
salesOrderId?: string | null;
}): FundingScope | null {
if (row.rentalAgreementId)
return { type: "rentalAgreement", id: row.rentalAgreementId };
if (row.salesOrderId) return { type: "salesOrder", id: row.salesOrderId };
return null;
}
/** Whether a source with this scope may fund the request's target. */
export function fundingScopeCovers(
scope: FundingScope | null | undefined,
request: Pick<FundingRequest, "rentalAgreementIds" | "salesOrderIds">
): boolean {
if (!scope) return true;
const ids =
scope.type === "rentalAgreement"
? request.rentalAgreementIds
: request.salesOrderIds;
return Boolean(ids?.includes(scope.id));
}
/** The refusal for applying a deposit to an invoice of another document. */
export function depositScopeMessage(scope: FundingScope): string {
const owner =
scope.type === "rentalAgreement" ? "that agreement's" : "that order's";
if (scope.readableId)
return `A deposit for ${scope.readableId} can only be applied to ${owner} invoices`;
return scope.type === "rentalAgreement"
? "A rental agreement deposit can only be applied to that agreement's invoices"
: "A sales order deposit can only be applied to that order's invoices";
}
function assertScope(scope: FundingScope | null | undefined): void {
if (!scope) return;
if (
(scope.type !== "rentalAgreement" && scope.type !== "salesOrder") ||
typeof scope.id !== "string" ||
!scope.id.trim()
) {
throw new Error("Funding source scope requires a document type and ID");
}
}
/** Allocation order: the current payment, then prior sources oldest first. */
function orderFundingSources<T extends FundingSource>(
currentPayment: T,
priorSources: readonly T[]
): T[] {
return [
currentPayment,
...[...priorSources].sort((a, b) => {
if (a.postingDate !== b.postingDate)
return a.postingDate < b.postingDate ? -1 : 1;
return a.paymentId < b.paymentId ? -1 : a.paymentId > b.paymentId ? 1 : 0;
})
];
}
export type FundingApplication = {
targetId: string;
sourcePaymentId: string | null;
sourceAmount: number;
sourceExchangeRate: number;
targetExchangeRate: number;
appliedAmount: number;
discountAmount: number;
writeOffAmount: number;
fxGainLossAmount: number;
};
function nonnegativeAmount(amount: number, label: string): number {
if (!Number.isFinite(amount) || amount < 0) {
throw new Error(`${label} must be nonnegative and finite`);
}
return amount;
}
function addUniqueId(ids: Set<string>, id: string, label: string): void {
if (typeof id !== "string" || !id.trim()) {
throw new Error(`${label} ID is required`);
}
if (ids.has(id)) throw new Error(`Duplicate ${label} ID: ${id}`);
ids.add(id);
}
/**
* Integer transport from origins to targets over an eligibility graph, filling
* the origins in list order: each origin sends as much as it can, through
* augmenting paths that may re-route an earlier origin's units to another
* eligible target but never reduce its total. The result is the
* lexicographically largest use of the origins in order (so the current
* payment is spent before any prior source, and prior sources oldest first),
* and it reaches every target any assignment could. With every edge eligible
* it is the plain staircase: origin by origin, targets in list order.
*/
function prioritizedTransport(
originUnits: readonly number[],
targetUnits: readonly number[],
eligible: (origin: number, target: number) => boolean
): number[][] {
const flow = originUnits.map(() => targetUnits.map(() => 0));
const edges = originUnits.map((_, o) =>
targetUnits.map((_, t) => eligible(o, t))
);
const spare = [...originUnits];
const open = [...targetUnits];
for (const [root] of originUnits.entries()) {
while (spare[root]! > 0) {
// Breadth-first: origin → eligible target; a full target hands one of
// its funding origins on to look for another target.
const reachedTargetFrom = targetUnits.map(() => -1);
const reachedOriginFrom = originUnits.map(() => -1);
const queue = [root];
let end = -1;
for (let head = 0; head < queue.length && end < 0; head++) {
const origin = queue[head]!;
for (const [target] of targetUnits.entries()) {
if (!edges[origin]![target] || reachedTargetFrom[target] !== -1)
continue;
reachedTargetFrom[target] = origin;
if (open[target]! > 0) {
end = target;
break;
}
for (const [other] of originUnits.entries()) {
if (
other !== root &&
reachedOriginFrom[other] === -1 &&
flow[other]![target]! > 0
) {
reachedOriginFrom[other] = target;
queue.push(other);
}
}
}
}
if (end < 0) break;
let amount = Math.min(spare[root]!, open[end]!);
for (let target = end; ; ) {
const origin = reachedTargetFrom[target]!;
if (origin === root) break;
target = reachedOriginFrom[origin]!;
amount = Math.min(amount, flow[origin]![target]!);
}
for (let target = end; ; ) {
const origin = reachedTargetFrom[target]!;
flow[origin]![target]! += amount;
if (origin === root) break;
target = reachedOriginFrom[origin]!;
flow[origin]![target]! -= amount;
}
spare[root]! -= amount;
open[end]! -= amount;
}
}
return flow;
}
/**
* Pure allocation after the caller validates company, party, side, currency and
* authoritative snapshots. Source/target document principal is independent of
* carrying base; final exhaustion releases each recorded carrying residual.
*/
export function allocatePaymentFunding(input: {
currentPayment: FundingSource;
priorSources: FundingSource[];
requests: FundingRequest[];
currencyDecimals: number;
isAR: boolean;
}): {
applications: FundingApplication[];
newOnAccountDocument: number;
sourceRemainders: Array<{
paymentId: string;
remainingDocument: number;
remainingBase: number;
}>;
} {
const { currencyDecimals, isAR } = input;
// This also validates the configured decimal count through the common boundary.
assertCurrencyDecimals(currencyDecimals);
const documentScale = 10 ** currencyDecimals;
const documentUnits = (amount: number, label: string): number => {
nonnegativeAmount(amount, label);
const normalized = toDocumentAmount(amount, 1, currencyDecimals);
// Admit only binary arithmetic noise, never a fraction of a document unit.
const noise = Number.EPSILON * Math.max(1, amount) * 4;
if (Math.abs(amount - normalized) > noise) {
throw new Error(`${label} exceeds document currency precision`);
}
const units = round(normalized * documentScale, 0);
if (!Number.isSafeInteger(units)) {
throw new Error(`${label} exceeds safe document currency units`);
}
return units;
};
const fromDocumentUnits = (units: number): number =>
toDocumentAmount(units / documentScale, 1, currencyDecimals);
const sourceIds = new Set<string>();
const sources = orderFundingSources(
input.currentPayment,
input.priorSources
).map((source) => {
addUniqueId(sourceIds, source.paymentId, "funding source");
assertExchangeRate(source.exchangeRate);
assertScope(source.scope);
const remainingUnits = documentUnits(
source.remainingDocument,
"Source amount"
);
const remainingBase = toBaseAmount(
nonnegativeAmount(source.remainingBase, "Source carrying base"),
1
);
if (remainingUnits === 0 && remainingBase !== 0) {
throw new Error(
`Exhausted source retains carrying base: ${source.paymentId}`
);
}
return {
...source,
remainingUnits,
remainingBase
};
});
const targetIds = new Set<string>();
const currentScope = input.currentPayment.scope;
const requests = input.requests.map((request) => {
addUniqueId(targetIds, request.targetId, "target");
// A deposit is applied only to its own document's invoices, whatever
// would fund the application — refused, not silently re-sourced.
if (currentScope && !fundingScopeCovers(currentScope, request))
throw new Error(depositScopeMessage(currentScope));
assertExchangeRate(request.targetExchangeRate);
const remainingUnits = documentUnits(
request.remainingDocument,
"Remaining target document amount"
);
const principalUnits = documentUnits(
request.requestedDocumentPrincipal,
"Requested document principal"
);
const remainingBase = toBaseAmount(
nonnegativeAmount(request.remainingBase, "Remaining target base"),
1
);
const discountAmount = toBaseAmount(
nonnegativeAmount(request.discountAmount, "Target discount amount"),
1
);
const writeOffAmount = toBaseAmount(
nonnegativeAmount(request.writeOffAmount, "Target write-off amount"),
1
);
const reliefBase = round(discountAmount + writeOffAmount);
const reliefUnits = documentUnits(
toDocumentAmount(
reliefBase,
request.targetExchangeRate,
currencyDecimals
),
"Target discount/write-off document amount"
);
if (
principalUnits + reliefUnits > remainingUnits ||
reliefBase > remainingBase
) {
throw new Error(
`Application exceeds target balance: ${request.targetId}`
);
}
const availablePrincipalBase = round(remainingBase - reliefBase);
const closesTarget = principalUnits + reliefUnits === remainingUnits;
if (closesTarget && principalUnits === 0 && availablePrincipalBase !== 0) {
throw new Error(
`Full target relief must release its remaining carrying base: ${request.targetId}`
);
}
const principalBase = closesTarget
? availablePrincipalBase
: Math.min(
toBaseAmount(
fromDocumentUnits(principalUnits),
request.targetExchangeRate
),
availablePrincipalBase
);
return {
...request,
discountAmount,
writeOffAmount,
principalUnits,
principalBase
};
});
// Which source funds how much of which request, decided over all requests
// at once: a deposit can fund only its own document's invoices, so a
// request-by-request walk could spend ordinary cash on a deposit's invoice
// and then refuse another invoice the deposit cannot reach — and whether it
// did would depend on the order the caller listed the requests in.
const flow = prioritizedTransport(
sources.map((source) => source.remainingUnits),
requests.map((request) => request.principalUnits),
(s, r) => fundingScopeCovers(sources[s]!.scope, requests[r]!)
);
requests.forEach((request, r) => {
const funded = flow.reduce((sum, row) => sum + row[r]!, 0);
if (funded < request.principalUnits)
throw new Error(
`Insufficient payment funding for target: ${request.targetId}`
);
});
const applications: FundingApplication[] = [];
for (const [r, request] of requests.entries()) {
let remainingUnits = request.principalUnits;
let remainingBase = request.principalBase;
let hasApplication = false;
if (remainingUnits === 0) {
if (request.discountAmount > 0 || request.writeOffAmount > 0) {
applications.push({
targetId: request.targetId,
sourcePaymentId: null,
sourceAmount: 0,
sourceExchangeRate: input.currentPayment.exchangeRate,
targetExchangeRate: request.targetExchangeRate,
appliedAmount: 0,
discountAmount: request.discountAmount,
writeOffAmount: request.writeOffAmount,
fxGainLossAmount: 0
});
}
continue;
}
// Applications follow source order within the request, so the arithmetic
// per (source, target) pair is the same as a plain walk's.
for (const [s, source] of sources.entries()) {
const units = flow[s]![r]!;
if (units === 0) continue;
const sourceAmount = fromDocumentUnits(units);
const appliedAmount =
units === remainingUnits
? remainingBase
: Math.min(
toBaseAmount(sourceAmount, request.targetExchangeRate),
remainingBase
);
const sourceBaseAmount =
units === source.remainingUnits
? source.remainingBase
: Math.min(
toBaseAmount(sourceAmount, source.exchangeRate),
source.remainingBase
);
applications.push({
targetId: request.targetId,
sourcePaymentId:
source.paymentId === input.currentPayment.paymentId
? null
: source.paymentId,
sourceAmount,
sourceExchangeRate: source.exchangeRate,
targetExchangeRate: request.targetExchangeRate,
appliedAmount,
discountAmount: hasApplication ? 0 : request.discountAmount,
writeOffAmount: hasApplication ? 0 : request.writeOffAmount,
fxGainLossAmount: calculateSettlementFx({
appliedAmount,
sourceAmount,
sourceExchangeRate: source.exchangeRate,
sourceBaseAmount,
isAR
})
});
hasApplication = true;
remainingUnits -= units;
remainingBase = round(remainingBase - appliedAmount);
source.remainingUnits -= units;
source.remainingBase = round(source.remainingBase - sourceBaseAmount);
}
}
const sourceRemainders = sources.map((source) => ({
paymentId: source.paymentId,
remainingDocument: fromDocumentUnits(source.remainingUnits),
remainingBase: source.remainingBase
}));
return {
applications,
newOnAccountDocument: sourceRemainders[0]?.remainingDocument ?? 0,
sourceRemainders
};
}
/**
* How much document principal each request could draw, earlier requests first,
* under the allocator's eligibility: a deposit only reaches invoices of its own
* document, and a deposit payment reaches nothing else. Feeding the results
* back as `requestedDocumentPrincipal` always allocates. `maximumDocument` caps
* a request (the invoice's open document amount, or an amount already entered);
* list the rows to keep first and the row to fill last to ask how much that row
* can add.
*/
export function fundableDocumentAmounts(input: {
currentPayment: FundingSource;
priorSources: readonly FundingSource[];
requests: ReadonlyArray<
Pick<FundingRequest, "rentalAgreementIds" | "salesOrderIds"> & {
maximumDocument: number;
}
>;
currencyDecimals: number;
}): number[] {
const { currencyDecimals } = input;
assertCurrencyDecimals(currencyDecimals);
const scale = 10 ** currencyDecimals;
const toUnits = (amount: number): number =>
Math.max(
0,
round(toDocumentAmount(amount, 1, currencyDecimals) * scale, 0)
);
const sources = orderFundingSources(input.currentPayment, input.priorSources);
const currentScope = input.currentPayment.scope;
// Requests are the origins here, so earlier requests are filled first.
const flow = prioritizedTransport(
input.requests.map((request) =>
currentScope && !fundingScopeCovers(currentScope, request)
? 0
: toUnits(request.maximumDocument)
),
sources.map((source) => toUnits(source.remainingDocument)),
(r, s) => fundingScopeCovers(sources[s]!.scope, input.requests[r]!)
);
return flow.map((row) =>
toDocumentAmount(
row.reduce((sum, units) => sum + units, 0) / scale,
1,
currencyDecimals
)
);
}
export type SettlementEffectiveness = {
paymentId: string | null;
memoId: string | null;
appliedViaPaymentId: string | null;
paymentStatus: string | null;
memoStatus: string | null;
viaStatus: string | null;
};
/** Parent status determines whether a persisted settlement has taken effect. */
export function isEffectiveSettlement(row: SettlementEffectiveness): boolean {
return row.paymentId
? row.paymentStatus === "Posted"
: Boolean(
row.memoId &&
row.memoStatus === "Posted" &&
(!row.appliedViaPaymentId || row.viaStatus === "Posted")
);
}
export type SettlementBalanceRow = {
targetSalesInvoiceId: string | null;
targetPurchaseInvoiceId: string | null;
/** An employee reimbursement settled by a disbursement to that employee.
* Nullable on every AR/AP row, so callers that never see one may pass
* `null` (or omit the column and spread it in). */
targetReimbursementId?: string | null;
sourceAmount: number | null;
appliedAmount: number;
discountAmount: number;
writeOffAmount: number;
};
function sourcePrincipal(value: number | null): number {
if (value === null)
throw new Error("Settlement is missing its document principal");
return nonnegativeAmount(Number(value), "Settlement document principal");
}
function settlementPrincipal(
row: { sourceAmount: number | null; appliedAmount: number },
exchangeRate: number,
decimals: number
): number {
if (row.sourceAmount !== null) return sourcePrincipal(row.sourceAmount);
return toDocumentAmount(
nonnegativeAmount(Number(row.appliedAmount), "Settlement applied amount"),
exchangeRate,
decimals
);
}
/** Accumulate first; each adjustment is rounded at its document boundary. */
export function reduceInvoiceSettlements(
rows: readonly Pick<
SettlementBalanceRow,
"sourceAmount" | "appliedAmount" | "discountAmount" | "writeOffAmount"
>[],
exchangeRate: number,
decimals: number
): { document: number; base: number } {
let document = 0;
let base = 0;
for (const row of rows) {
const adjustments =
nonnegativeAmount(Number(row.discountAmount), "Settlement discount") +
nonnegativeAmount(Number(row.writeOffAmount), "Settlement write-off");
document +=
settlementPrincipal(row, exchangeRate, decimals) +
toDocumentAmount(adjustments, exchangeRate, decimals);
base +=
nonnegativeAmount(
Number(row.appliedAmount),
"Settlement applied amount"
) + adjustments;
}
return {
document: toDocumentAmount(document, 1, decimals),
base: round(base)
};
}
/** Original controls use signed natural balances for both AR and AP.
*
* `isReimbursement` selects the third target column. An employee
* reimbursement is a TARGET exactly like a payable invoice — a liability with
* a carrying value that prior settlements draw down — so it nets the same way;
* only the column its settlements are keyed on differs. It is a separate flag
* rather than a third `isAR` state because `isAR` still answers a different
* question here (which side of the ledger), and a reimbursement is always the
* payable side. */
export function invoiceRemainingAmounts(
invoice: {
id: string | null;
totalAmount: number | null;
exchangeRate: number | null;
},
rows: readonly SettlementBalanceRow[],
controlAmounts: ReadonlyMap<string, number>,
decimals: number,
isAR: boolean,
isReimbursement = false
): { remainingDocument: number; remainingBase: number } {
if (
!invoice.id ||
invoice.totalAmount == null ||
invoice.exchangeRate == null
) {
throw new Error("Invoice identity, total or exchange rate is missing");
}
const rate = Number(invoice.exchangeRate);
const targetOf = (row: SettlementBalanceRow): string | null | undefined =>
isReimbursement
? row.targetReimbursementId
: isAR
? row.targetSalesInvoiceId
: row.targetPurchaseInvoiceId;
const consumed = reduceInvoiceSettlements(
rows.filter((row) => targetOf(row) === invoice.id),
rate,
decimals
);
const originalDocument = toDocumentAmount(
Number(invoice.totalAmount),
rate,
decimals
);
const remainingDocument = toDocumentAmount(
originalDocument - consumed.document,
1,
decimals
);
const originalBase =
controlAmounts.get(invoice.id) ?? round(Number(invoice.totalAmount));
const remainingBase = round(originalBase - consumed.base);
if (
!Number.isFinite(remainingBase) ||
remainingDocument < 0 ||
remainingBase < 0
) {
throw new Error(
"Invoice already has excessive settlements or an invalid carrying balance"
);
}
return { remainingDocument, remainingBase };
}
export type FundingPaymentRow = {
id: string;
totalAmount: number;
exchangeRate: number;
postingDate: string | null;
paymentDate: string;
currencyCode: string;
/** A deposit's document (`fundingScopeOf`), carried onto the source. */
scope?: FundingScope | null;
};
export type FundingConsumptionRow = {
paymentId: string | null;
sourcePaymentId: string | null;
sourceAmount: number | null;
appliedAmount: number;
fxGainLossAmount: number | null;
};
/** Callers select effective payments or reserved memos before reducing money. */
export function remainingFundingSources(
payments: readonly FundingPaymentRow[],
consumption: readonly FundingConsumptionRow[],
decimals: ReadonlyMap<string, number>,
isAR: boolean
): FundingSource[] {
const precisionFor = (payment: FundingPaymentRow): number => {
const precision = decimals.get(payment.currencyCode);
if (precision == null)
throw new Error(
`Currency ${payment.currencyCode} requires configured decimal places`
);
return precision;
};
const paymentsById = new Map(
payments.map((payment) => [payment.id, payment])
);
const consumed = new Map<string, { document: number; base: number }>();
for (const row of consumption) {
const sourceId = row.sourcePaymentId ?? row.paymentId;
if (!sourceId) continue;
const current = consumed.get(sourceId) ?? { document: 0, base: 0 };
if (row.sourceAmount === null && row.sourcePaymentId === null) {
const payment = paymentsById.get(sourceId);
if (!payment) continue;
current.document += settlementPrincipal(
row,
Number(payment.exchangeRate),
precisionFor(payment)
);
} else {
current.document += sourcePrincipal(row.sourceAmount);
}
const fx = Number(row.fxGainLossAmount ?? 0);
if (!Number.isFinite(fx)) throw new Error("Settlement FX must be finite");
current.base +=
nonnegativeAmount(
Number(row.appliedAmount),
"Settlement applied amount"
) +
(isAR ? 1 : -1) * fx;
consumed.set(sourceId, current);
}
return payments
.map((payment) => {
const precision = precisionFor(payment);
const use = consumed.get(payment.id);
const total = nonnegativeAmount(
Number(payment.totalAmount),
"Funding document total"
);
const remainingDocument = toDocumentAmount(
total - (use?.document ?? 0),
1,
precision
);
const remainingBase = round(
toBaseAmount(total, Number(payment.exchangeRate)) - (use?.base ?? 0)
);
if (
remainingDocument < 0 ||
remainingBase < 0 ||
(remainingDocument === 0 && remainingBase !== 0)
) {
throw new Error(
`Invalid remaining funding balance for payment ${payment.id}`
);
}
const source: FundingSource = {
paymentId: payment.id,
postingDate: payment.postingDate ?? payment.paymentDate,
exchangeRate: Number(payment.exchangeRate),
remainingDocument,
remainingBase
};
if (payment.scope) source.scope = payment.scope;
return source;
})
.filter((payment) => payment.remainingDocument > 0);
}